zmb3 / gogetdoc Goto Github PK

Before submitting an issue, please make sure:

• You're running Go 1.6 or later
• You've tried installing with go get -u to update dependencies

If you see the following error, you need to update to Go 1.6+:

$ go get github.com/zmb3/gogetdoc
# github.com/zmb3/gogetdoc
./ident.go:142: c.Val().ExactString undefined (type constant.Value has no field or method ExactString)

It would be useful to have the installation instructions in the README.md, not just the issue template.

Add support for multiple output formats. For example, consider the following output types:

• HTML
• JSON
• Go template language

This would allow editors to do fancy things like display the title in a different size, use fixed-width font for argument names, etc.

It looks like test files are not considered when loading the initial program.

Attempting to run the tool on a test file produces the following output:

gogetdoc: couldn't find /path/to/file_test.go in program

So gogetdoc does its job just awesomely well, but this minor quirk bugs me from time to time as slightly irritating: it returns the current-package doc-comment / summary for stuff like operators, keywords, whitespace.. nigh-on anything, seemingly, it couldn't possibly find any docs for to begin with. Would be cool if there was either a flag to not do this, or (possibly more straightforward & robust to add) and a new omitempty JSON field that signifies, if set, that the current summary returned was said fallback, so consumers can filter these out should they wish to =)

See microsoft/vscode-go#1024

gogetdoc fails to give definition info when there is a build tag in the file

Before submitting an issue, please make sure:

• [ x ] You're running Go 1.6 or later
• [ x ] You've tried installing with go get -u to update dependencies

I'm calling gogetcode from the Golang Emacs layer. If I try to fetch a doc for a package that has been vendored then I get an import map mismatch.

package github.com/wata727/tflint/vendor/github.com/mitchellh/go-homedir not in import map of packages github.com/wata727/tflint/plugin/discovery

Fetching documentation from stdlib works fine.

Scenario: editing a .go file that's hasn't been saved yet. (For example, for rapid greenfield prototyping of stuff via some sort of go run-based REPL-ish tool like gore.) The source is sent as usual via -modified flag and stdin archive format. When -pos is something like Untitled-1.go:#pos, all documentation requests via -json (say, hovering over the strings.ToLower or anything that should have docs) will always return couldn't find Untitled-1 in program. Or if name is empty, similarly couldn't find in program (2 spaces).

Here's an easy-repro session:

[23:42 me ~/.../github.com/metaleap]$ gogetdoc -json -modified -pos untitled.go:#94
untitled.go
136
package tmp
import "strings"
func test (val string) string {
	if val[0]=='u' {return strings.ToUpper(val)}
	return "Nope not happn'g"
}
gogetdoc: couldn't find untitled.go in program
[23:49 me ~/.../github.com/metaleap]$ 

Of course no file named untitled.go exists on disk, but would be awesome if gogetdoc could handle that, given that it read the program from stdin anyway! The given -pos 94 should be between the T and o of ToUpper if my editor didn't fool me.

I can do a PR if you're open to the idea. Which would be: renaming package main to package gogetdoc, turning the current func main() into an exported func Main() to be then called from a newly added package main cmd importing the above..

Not crucial, just would be neat! I prefer libs over external cmd's for stuff like this as it needs to be installed separately by the user (or added to deployment workload/complexity) and there's no 100% version guarantee like there is with static-linked-import of tool-as-a-lib =)

Even under go1.6, I can't get it to build

% go build
# github.com/zmb3/gogetdoc
./ident.go:18: impossible type assertion:
    *"go/types".PkgName does not implement "golang.org/x/tools/go/types".Object (wrong type for Parent method)
        have Parent() *"go/types".Scope
        want Parent() *"golang.org/x/tools/go/types".Scope
% go version
go version go1.6 darwin/amd64

Any ideas?

When looking at an anonymous field, developers are most interested in the doc and contents of the type, not the doc for the field itself.

Originally reported at microsoft/vscode-go#1044

Before submitting an issue, please make sure:

• You're running Go 1.6 or later - later
• You've tried installing with go get -u to update dependencies - yes

I write tests with build tag. And i tried see documentation in this file. I recieve followed error:
gogetdoc: couldn't find /.../file_test.go in program.

I understand where it come from. And is it possible to fix it?

Right now, the only way to enable cgo is to modify the source of gogetdoc. Please add a command line flag for it. cgo_enabled is necessary to get docs for packages that use cgo.

Would it be possible to return full package documentation like the output of godoc with the full docs for the package and all of the exported things.

In contrast to the current behavior of only showing the package level docs when pointing at a package. Also in contrast to the go doc behavior of showing just the package level docs and a list of the other exported things.

I've actually been able to chain gogetdoc to find the package location (to correctly handle things like vendor overrides and packages that only appear in the vendor directory), and godoc. But that was done manually. I'm sure I could script it, but it may be generally handy to get the full package docs.

Asking in conjunction with microsoft/vscode-go#1237

VS Code Issue reference: microsoft/vscode-go#2084

Turns out gogetdoc gets stuck when operating on files with errors.

Sample code:

package main

import (
	"fmt"
	"io/ioutil"
	"os"
)

func main() {
	fmt.Pri ntln("hallo")
	ioutil.ReadAll(os.Stdin)
}

Run gogetdoc on the ReadAll symbol with the above code. gogetdoc will be stuck and not return results

Try again after fixing the Println. Everything would be fine now.

Current master (e2fdf30) fails to build upon go get with:

➜  gogetdoc git:(master) go build
# github.com/zmb3/gogetdoc
./ident.go:142: c.Val().ExactString undefined (type constant.Value has no field or method ExactString)

I had to go back to 4a5247b to get to a buildable commit.

foo.h

#ifndef __FOO_H__
#define __FOO_H__

inline void foo(void)
{
}

#endif//__FOO_H__

foo.go

// Package foo is just any package
package foo

/*
#include "foo.h"
*/
import "C"

// Foo calls the foo function in C
func Foo() {
    C.foo()
}

bar.go

package foo

// Bar calls Foo
func Bar() {
    Foo()
}

gogetdoc for foo.Foo and foo.Bar and see the former fails and the latter succeeds

$ gogetdoc -pos "foo.go:#125"
xxx/bar.go:5:2: undeclared name: Foo
gogetdoc: couldn't find foo.go in program
$ gogetdoc -pos "bar.go:#37"
import "xxx/foo"

func Bar()

Bar calls Foo

Now change bar.go to import "C"

package foo

/*
void bar()
{
}
*/
import "C"

// Bar calls Foo
func Bar() {
    C.bar()
}

then run gogetdoc for foo.Bar

 $ gogetdoc -pos "bar.go:#70"
gogetdoc: couldn't find bar.go in program

The code for handling -modified archives and the overlay context now exists in golang.org/x/tools/go/buildutil – the question is whether you want to use that, or keep using the version we have in gogetdoc. Using buildutil would mean less code for us to manage, but if people already have an old copy of it checked out, and don't use go get -u to install gogetdoc, they'll get build failures.

Up to you. I'll happily send a PR if you decide to use buildutil.

This could be an issue on my side, but I got an error when calling vim-go's :GoInstallBinaries.

../../zmb3/gogetdoc/ident.go:142: c.Val().ExactString undefined (type constant.Value has no field or method ExactString)

As vgo has been accepted, would be great to get gogetdoc updated to find the right docs based on the source location under $GOPATH/src/v.

See microsoft/vscode-go#1532 (comment)

Seems like gogetdoc (or, rather, go list?) is unable to get documentation for stdlib packages with GO111MODULE=on (/Users/nezorflame/.gvm/gos/go1.11.4 is where my Go is installed, through gvm):

Input:
~ gogetdoc -pos=/Users/nezorflame/.gvm/gos/go1.11.4/src/fmt/print.go:#7660

Output:
cannot load package containing /Users/nezorflame/.gvm/gos/go1.11.4/src/fmt/print.go: go [list -e -json -compiled -test=false -export=false -deps=true -- /Users/nezorflame/.gvm/gos/go1.11.4/src/fmt]: exit status 1: go: cannot determine module path for source directory /Users/nezorflame/.gvm/gos/go1.11.4 (outside GOPATH, no import comments)

If I explicitly set GO111MODULE=auto (or off) before invoking it, it works:

Input:
~ GO111MODULE=auto gogetdoc -pos=/Users/nezorflame/.gvm/gos/go1.11.4/src/fmt/print.go:#7660

Output:

import "fmt"

func Fprintln(w io.Writer, a ...interface{}) (n int, err error)

Fprintln formats using the default formats for its operands and writes to w.
Spaces are always added between operands and a newline is appended. It returns
the number of bytes written and any write error encountered.

Details on that issue can be found here: microsoft/vscode-go#2213

Given the following project in GOPATH

.
├── main.go
└── prom
    └── metrics.go

//main.go
package main

import (
	"gogetdocbug/prom"
	//_ "github.com/prometheus/client_golang/prometheus"
)

func main() {
	//gogetdoc this line
	prom.Metric.Inc()
}

//prom/metrics.go
package prom

import (
	"github.com/prometheus/client_golang/prometheus"
)

//this works
var Metric prometheus.Counter

If I execute gogetdoc -pos main.go:#145, which points to .Metric, I get correct results

import "gogetdocbug/prom"

var Metric *CounterVec

this works

But gogetdoc -pos main.go:#150, which points to .Inc, returns

no documentation found for Inc

If I uncomment import tag, the same command returns correct results. It looks like this is not limited to prometheus but happens in general when you request documentation for symbol that's from a package not imported directly.

go version go1.11.2 darwin/amd64
gogetdoc is on the latest version

I am using VS Code, which uses gogetdoc to get symbol hover/mouseover information.

Since gogetdoc does not return package information with the symbol information (as I understand it), VS Code is not able to display the package name of the symbol (see microsoft/vscode-go#1085)

Would it be possible for gogetdoc to return the package name with each symbol?

Run go get -u github.com/zmb3/gogetdoc to get the error

.../github.com/zmb3/gogetdoc/vendor/golang.org/x/tools/go/packages/packages.go:695: undefined: types.SizesFor

cc @zmb3

gogetdoc seems to invoke cgo, which invokes the native compiler, which can be quite slow. It does this for every invocation, with no caching, even if there were no changes in the cgo code. This ends up making gogetdoc so slow that it is unusable when you have such a package in your dependency graph.

Steps to reproduce

You need to have ImageMagick available. (See https://github.com/gographics/imagick)

1. Save the following as main.go in a new go package directory:

package main

import "gopkg.in/gographics/imagick.v2/imagick"

func main() {
	imagick.Initialize()
}

2. dep init.
3. gogetdoc -pos main.go:#87.

Related

microsoft/vscode-go#667 microsoft/vscode-go#1025

cc @ramya-rao-a

Just ran go get -u github.com/zmb3/gogetdoc and this gives me a build error.

github.com\zmb3\gogetdoc\main.go:77: undefined: buildutil.ParseOverlayArchive
github.com\zmb3\gogetdoc\main.go:81: undefined: buildutil.OverlayContext

My go version is 1.6.2 windows/amd64

As of
ba76b40, gogetdoc doesn't work with the -modified flag

I am using gogetdoc in VS Code which uses the -modified flag by default.
It works as expected when I changed the VS Code extension to not use the -modified flag

cc @zmb3

fatal error: all goroutines are asleep - deadlock!

goroutine 1 [chan receive]:
main.Load(0xc00005c090, 0x7, 0x0, 0x0, 0x0, 0x7, 0x2, 0x3, 0x0, 0x0)
        D:/GO_DATA/src/github.com/zmb3/gogetdoc/main.go:198 +0x4fd
main.Run(0xc00005c090, 0x7, 0x0, 0x0, 0x0, 0x0, 0x0)
        D:/GO_DATA/src/github.com/zmb3/gogetdoc/main.go:207 +0x54
main.main()
        D:/GO_DATA/src/github.com/zmb3/gogetdoc/main.go:90 +0x1c3

go version go1.11.4 windows/amd64

Occurs if given input document contains errors and the parser returns an error.

The parser error should be ignored if file is not nil (return documentation if you can, especially if the input file contains syntax errors). If the file is null and is input file we need to return the error via the channel.

proposed fix:

file, err := parser.ParseFile(fset, fname, src, mode)
		if file == nil   {
                        if (err==nil){
                             err=errors.New('Inputfile failed to parse.')
                        }
                        if isInputFile {
			     ch <- result{nil, err}
                        }
			return nil, err
		}

Editor files often aren't yet saved to disk, so the files read will be wrong WRT the editor. guru (formerly oracle) has the option. Using its same input format would be great (I maintain an editor plugin and not having to support another file format would be awesome.)

I've run into this a few times, and I've finally dug into what I'm seeing. I'm not sure what is causing it, or if it's actually expected. When you request the documentation for an interface method the type names display as the full path to the type instead of what appears to be the standard format of package.type or type that appears in the rest of the displayed documentation. Is there any way to get gogetdoc to print the more human readable version of the type when grabbing the documentation for a interface method?

I've created a simple go file that has the behavior I'm experiencing

package rabbit

// Thing is an interface
type Thing interface {

	// Do does a thing
	Do(s Stuff) Stuff
}

// Stuff is a struct
type Stuff struct{}

// ThingImplemented matches Thing interface
type ThingImplemented struct{}

// Do does stuff
func (ti *ThingImplemented) Do(s Stuff) Stuff {
	return s
}

When executing gogetdoc against the interface Do method I receive this out put

SteelPhase@mac:rabbit$gogetdoc -pos example.go:#86 -json | jq
{
  "name": "Do",
  "import": "github.com/SteelPhase/rabbit",
  "pkg": "rabbit",
  "decl": "func (github.com/SteelPhase/rabbit.Thing).Do(s github.com/SteelPhase/rabbit.Stuff) github.com/SteelPhase/rabbit.Stuff",
  "doc": "Do does a thing\n",
  "pos": "/Users/SteelPhase/Code/Go/src/github.com/SteelPhase/rabbit/example.go:7:2"
}

I was expecting to see

SteelPhase@mac:rabbit$gogetdoc -pos example.go:#86 -json | jq
{
  "name": "Do",
  "import": "github.com/SteelPhase/rabbit",
  "pkg": "rabbit",
  "decl": "func (Thing).Do(s Stuff) Stuff",
  "doc": "Do does a thing\n",
  "pos": "/Users/SteelPhase/Code/Go/src/github.com/SteelPhase/rabbit/example.go:7:2"
}

As an addition example, when you request the documentation for ThingImplemented's Do method you get this

SteelPhase@mac:rabbit$gogetdoc -pos example.go:#270 -json | jq
{
  "name": "Do",
  "import": "github.com/SteelPhase/rabbit",
  "pkg": "rabbit",
  "decl": "func (ti *ThingImplemented) Do(s Stuff) Stuff",
  "doc": "Do does stuff\n",
  "pos": "/Users/SteelPhase/Code/Go/src/github.com/SteelPhase/rabbit/example.go:17:29"
}

For reasons I can't get into publicly, I'm working on Go code that doesn't conform to the standard package layout.

The line at https://github.com/zmb3/gogetdoc/blob/master/main.go#L110 causes the whole thing to bail in this case.

I understand that supporting weird package layouts isn't useful, but could there be some workaround so at least if you're trying to get to the standard libraries it still works?

package main                                                                    
                                                                                
import (                                                                        
    "log"                                                                       
                                                                                
    "github.com/veandco/go-sdl2/sdl"                                            
)                                                                               
                                                                                
func main() {                                                                   
    err := sdl.Init(sdl.INIT_EVERYTHING)                                        
    if err != nil {                                                             
        log.Fatalf("Unable to init SDL")                                        
    }                                                                           
    defer sdl.Quit()                                                                                                                                        
}

$gogetdoc -pos main.go:#95 // the Init call

It returns an error: $GOPATH/src/github.com/veandco/go-sdl2/sdl/yuv_sw_c.go:17:16: undeclared name: Surface gogetdoc: no documentation found

This is a great tool for gophers.
But it can not support jump to source for builtin package, for example: println can only get doc, but no position.
Could you add this?
Thanks

if import some lib like ". github.com/a/b", can't goto definition which define in b.
function is also undefined.

// b.go
type GlobalConfig struct {
	Localaddr string
}
func InitGlobalVars(globalconfig *GlobalConfig) error {
}


// main.go
import (
. github.com/a/b
)
// can't goto definition
globalconfig := &GlobalConfig{}
// InitGlobalVars is undefined
InitGlobalVars(globalconfig)

$ go get github.com/zmb3/gogetdoc
# github.com/zmb3/gogetdoc
./ident.go:142: c.Val().ExactString undefined (type constant.Value has no field or method ExactString)

Is it possible to set a tag to older version then it is workable for Go 1.5.1( Centos 6 newest Go version)
eg. 4ecb996

To illustrate what I mean, consider that one currently has to hard-code special non-JSON-output cases as one accidentally runs into them, e.g.:

metaleap/go-util@c82fa0d#diff-3482478175d30d20e81d5d6ff7611d61R253

(One will note in the above that the special non-JSON-output cases do indeed occur not over stderr but stdout.)

Nothing urgent of course.. just noting it down here for the record, in case any contributor (perhaps even me in the future) feels at leisure to tweak the program's output behaviors with -json on =)

From @enitihas on January 2, 2017 3:59

I recently changed the option "go.docsTool" to gogetdoc. However, now when I hover over a local variable in any function, it shows me the function name instead of type information of the variable. However, hover works correctly for function arguments.

Copied from original issue: microsoft/vscode-go#703