Initial commit

Author: zmb3

LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2016, Zac Bergquist
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of gogetdoc nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,42 @@
+gogetdoc
+========
+
+Retrieve documentation for items in Go source code.
+
+Go has a variety of tools that make it easy to lookup documentation.
+There's the `godoc` HTTP server, the `go doc` command line tool, and https://godoc.org.
+
+These tools are great, but in many cases one may find it valuable to lookup
+documentation right from their editor.  The problem with all of these tools
+is that they are all meant to be used by a person who knows what they are
+looking for.  This makes editor integration difficult, as there isn't an easy way
+to say "get me the documentation for this item here."
+
+The `gogetdoc` tool aims to make it easier for editors to provide access to
+Go documentation.  Simply give it a filename and offset within the file and
+it will figure out what what you're referring to and find the documentation
+for it.
+
+## Prerequisites
+
+This tool **requires Go 1.6**, which is currently available by building from tip
+or by installing the Go 1.6 release candidate from https://golang.org/dl/.
+
+## Contributions
+
+Are more than welcome!  For small changes feel free to open a pull request.
+For larger changes or major features please open an issue to discuss.
+
+## Credits
+
+The following resources served as both inspiration for starting this tool
+and help coming up with the implementation.
+
+- Alan Donovan's GothamGo talk "Using `go/types` for Code Comprehension
+  and Refactoring Tools" https://youtu.be/p_cz7AxVdfg
+- Fatih Arslan's talk at dotGo 2015 "Tools for working with Go Code"
+- The `go/types` example repository: https://github.com/golang/example/tree/master/gotypes
+
+## License
+
+3-Clause BSD license - see the LICENSE file for details.

ident.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"fmt"
+	"go/ast"
+	"go/token"
+	"go/types"
+
+	"golang.org/x/tools/go/loader"
+)
+
+// IdentDoc attempts to get the documentation for a *ast.Ident.
+func IdentDoc(id *ast.Ident, info *loader.PackageInfo, prog *loader.Program) (*Doc, error) {
+	// get definition of identifier
+	obj := info.ObjectOf(id)
+
+	// handle packages imported under a different name
+	if p, ok := obj.(*types.PkgName); ok {
+		return PackageDoc(prog.Fset, p.Imported().Path())
+	}
+
+	_, nodes, _ := prog.PathEnclosingInterval(obj.Pos(), obj.Pos())
+	for _, node := range nodes {
+		//fmt.Printf("for %s: found %T\n%#v\n", id.Name, node, node)
+		switch n := node.(type) {
+		case *ast.FuncDecl:
+			return &Doc{
+				Name:  obj.Name(),
+				Title: obj.String(), // TODO "relative-to" output format...
+				Doc:   n.Doc.Text(),
+			}, nil
+		case *ast.GenDecl:
+			var constValue string
+			if n.Tok == token.CONST {
+			SpecLoop:
+				for _, s := range n.Specs {
+					vs := s.(*ast.ValueSpec)
+					for _, val := range vs.Values {
+						if bl, ok := val.(*ast.BasicLit); ok {
+							if bl.Value != "" {
+								constValue = bl.Value
+								break SpecLoop
+							}
+						}
+					}
+				}
+			}
+			if n.Doc != nil {
+				d := &Doc{
+					Name:  obj.Name(),
+					Title: obj.String(),
+					Doc:   n.Doc.Text(),
+				}
+				if constValue != "" {
+					d.Doc += fmt.Sprintf("\nConstant Value: %s", constValue)
+				}
+				return d, nil
+			}
+		case *ast.Field:
+			// check the doc first, if not present, then look for a comment
+			if n.Doc != nil {
+				return &Doc{
+					Name:  obj.Name(),
+					Title: obj.String(),
+					Doc:   n.Doc.Text(),
+				}, nil
+			} else if n.Comment != nil {
+				return &Doc{
+					Name:  obj.Name(),
+					Title: obj.String(),
+					Doc:   n.Comment.Text(),
+				}, nil
+			}
+		}
+	}
+	return nil, fmt.Errorf("No documentation found for %s", obj.Name())
+}

ident_test.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"strings"
+	"testing"
+
+	"golang.org/x/tools/go/loader"
+)
+
+const funcDecl = `package main
+
+import (
+	"fmt"
+	mth "math"
+)
+
+type X struct{}
+
+// SayHello says hello.
+func (X) SayHello() {
+  fmt.Println("Hello, World", mth.IsNaN(1.23))
+}
+
+func main() {
+  var x X
+  x.SayHello()
+  SayGoodbye()
+}
+
+// SayGoodbye says goodbye.
+func SayGoodbye() {
+  fmt.Println("Goodbye")
+  fmt.Println(Message, fmt.Sprintf("The answer is %d", Answer))
+}
+
+// Message is a message.
+var Message = "This is a test."
+
+// Answer is the answer to life the universe and everything.
+const Answer = 42
+
+type Foo struct {
+	// FieldA has doc
+	FieldA string
+	FieldB string // FieldB has a comment
+}
+
+func (f Foo) Print() {
+	fmt.Println(f.FieldA, f.FieldB)
+}
+`
+
+func TestIdent(t *testing.T) {
+	t.Parallel()
+	conf := &loader.Config{
+		ParserMode: parser.ParseComments,
+	}
+	astFile, err := conf.ParseFile("test.go", funcDecl)
+	if err != nil {
+		t.Error(err)
+	}
+
+	conf.CreateFromFiles("main", astFile)
+	prog, err := conf.Load()
+	if err != nil {
+		t.Error(err)
+	}
+
+	tokFile := FileFromProgram(prog, "test.go")
+	if tokFile == nil {
+		t.Error("Couldn't get token.File from program")
+	}
+
+	tests := []struct {
+		Pos token.Pos
+		Doc string
+	}{
+		{tokFile.Pos(191), "SayHello says hello.\n"},                                                              // method call
+		{tokFile.Pos(205), "SayGoodbye says goodbye.\n"},                                                          // function call
+		{tokFile.Pos(305), "Message is a message.\n"},                                                             // var (use)
+		{tokFile.Pos(388), "Message is a message.\n"},                                                             // var (definition)
+		{tokFile.Pos(318), "Sprintf formats according to a format specifier and returns the resulting string.\n"}, // std func
+		{tokFile.Pos(346), "Answer is the answer to life the universe and everything.\n\nConstant Value: 42"},     // const (use)
+		{tokFile.Pos(484), "Answer is the answer to life the universe and everything.\n\nConstant Value: 42"},     // const (definition)
+		{tokFile.Pos(144), "IsNaN reports whether f is an IEEE 754 ``not-a-number'' value.\n"},                    // std func call (alias import)
+		{tokFile.Pos(628), "FieldA has doc\n"},
+		{tokFile.Pos(637), "FieldB has a comment\n"},
+	}
+TestLoop:
+	for _, test := range tests {
+		info, nodes, _ := prog.PathEnclosingInterval(test.Pos, test.Pos)
+		for i := range nodes {
+			if ident, ok := nodes[i].(*ast.Ident); ok {
+				doc, err := IdentDoc(ident, info, prog)
+				if err != nil {
+					t.Fatal(err)
+				}
+				if !strings.EqualFold(test.Doc, doc.Doc) {
+					t.Errorf("Want '%s', got '%s'\n", test.Doc, doc.Doc)
+				}
+				continue TestLoop
+			}
+		}
+		t.Errorf("Coudln't find *ast.Ident at %s\n", prog.Fset.Position(test.Pos))
+	}
+}