godoc and build tags

[Eric Gavaletz]

I have been working with a group building a project for GAE this summer (GSoC), and we are at the end of the term and tidying up documentation.  I asked the students to make sure that their code is neatly packaged, and that the package documentation is linked to from the design document.  One of the students pointed out that because we are using build tags to specify which files have an appengine dependency (necessary for local unit testing to work on the non-GAE portions of a package and to make the project go getable) those files are not included when godoc is used.

In the short term we will just link to the source, but this is not a problem that is specific to GAE.  Any package file that uses a build tag seems to be excluded from godoc processing.  I found some talk about the mess that could result from having too much markup in the documentation, but has there been discussion of supporting the -tags argument for godoc, or maybe supplying a // +build godoc tag for indicating that we do want this file to be included?

It looks like if I use the build tag:

// +build appengine linux

That it will include the documentation for appengine, but it will also break the ability to cleanly go get the code which makes local unit testing a bit of a mess.  This (among other issues) goes back to how appengine not an external library, and it does not play well with the normal standard library.

[Kyle Lemons]

This is definitely something that I'd like to see happen too, but it doesn't look like anyone had the bandwidth to get it done for go1.2:

http://golang.org/issue/3398

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Eric Gavaletz]

There has also been a little discussion on this issue from the guy doing godoc.org.  

https://github.com/garyburd/gddo/issues/113

[Kyle Lemons]

On Sun, Sep 22, 2013 at 3:43 PM, Eric Gavaletz <gava...@gmail.com> wrote:

There has also been a little discussion on this issue from the guy doing godoc.org.  

https://github.com/garyburd/gddo/issues/113

For a shared service like godoc.org, it would have to either (a) recompute the docs to show based on ?query arguments or (b) compute every combination of the build tags used by the package.  For a single godoc instance, a -tags flag should be able to specify what he describes there (the build context to use).  In other words, `godoc -tags appengine` would only show files that would build under `go build -tags appengine`, which would consequently not process "// +build !appengine" files.  Having not looked at the code I can't say for sure, but it seems like it would be the moral equivalent of stitching a flag through to the http://golang.org/pkg/go/build/#Context.BuildTags that's grabbing files.