Allow showing documentation for the main package

[ElPincheTopo]

I understand that the use of the documentation that godoc generates is to help the developers that import a library, but it would be useful to devs working on a single package app to be able to generate the documentation for the main package.

I think the best way to implement this is with a parameter in the url when accessing the package name, so we don't change the default behavior, but also make it accessible in https://godoc.org/

It could also be enabled by default. This way if one wants to get the functions in the main package added to the documentation you simply write the names with a starting uppercase letter.

[adg]

What is it that you want exactly?

The godoc tool and godoc.org already display documentation for commands. For example: https://godoc.org/golang.org/x/tools/cmd/godoc

[ElPincheTopo]

I want the documentation to be able to show the functions in package main, not only the comment on top of the main package declaration.

[dominikh]

@adg this is essentially golang/go#5727

[adg]

Ah right. Yes, reasonable feature request. Probably not difficult to implement either.

[dmitshur]

Two comments:

1. this is essentially x/pkgsite: option to show "exported" declarations of main packages go#5727

   When writing libraries, people think carefully about whether each identifier should be exported or not, because it affects the API of the library and what is seen on godoc. When writing commands, people can use different criteria for deciding between unexported and exported.

   If godoc.org begins to display (or has the option to display) only the exported identifiers, will that mean people should change their strategy about how to make that decision, in order to have better documentation on godoc.org? Would that be a good thing?

   What does it means to have "documentation" for a command - it's not a library, and you can't import any of its exported or unexported funcs. I think the current behavior of showing only the package summary of the command (e.g., https://godoc.org/golang.org/x/tools/cmd/godoc) is the right way about showing documentation.

   Please correct me if I'm wrong, but it seems to me that in this feature request and in the one linked by @dominikh x/pkgsite: option to show "exported" declarations of main packages go#5727, the underlying desire is not to view some sort of documentation for a command's exported funcs, but rather to see its source code (at least partially). If so, why not use a dedicated tool for viewing source code of a Go package, such as https://gotools.org/golang.org/x/tools/cmd/godoc, instead of changing the definition of "documentation" for a command and hoping godoc.org can show it?

   For disclosure, I had the same wishlist/desire for godoc and/or godoc.org to display more of what's inside commands, and I was unsatisfied with the limited options they provided, which led to created gotools.org that was dedicated to resolving the specific task of seeing source code of a Go package directly.

2. Right now, aside from extra options like viewing imports graph, etc., godoc.org is essentially configuration free. Each page is predictable and can be navigated to by simply going to https://godoc.org/ + import path.

   If feature is implemented as optional, there'd need to be some UI or way of changing how godoc.org displays documentation for commands. What are some ways that could be done? Are we going to ensure it doesn't sacrifice the overall usability of godoc.org?

That's all for now, I wanted to share those two thoughts and I'm happy to discuss them.

[ElPincheTopo]

@shurcooL I think that the possibility to see the commands functions and a description of what does it function does (just as it is displayed for libraries) is very useful for the devs working on the command.

Perhaps the best way to implement this is with a URL parameter. Currently it accepts all,methods,src,text,flat I think we can add a cmd parameter to show the doc for commands. This way there is no change in the usage but the people that found this feature useful can take advantage of it.

[dmitshur]

@shurcooL I think that the possibility to see the commands functions and a description of what does it function does (just as it is displayed for libraries) is very useful for the devs working on the command.

I can see that being somewhat useful, but when you're actually working on a command, you may have some changes that are not yet committed or not yet pushed remotely. godoc.org won't be able to display those. A local cmd/godoc process can display both, so it seems more useful to have this functionality there IMO.

Perhaps the best way to implement this is with a URL parameter. Currently it accepts all,methods,src,text,flat I think we can add a cmd parameter to show the doc for commands. This way there is no change in the usage but the people that found this feature useful can take advantage of it.

That sounds like the best kind of UI for this, I agree.

[mjmac]

Throwing in a slightly different use case: c-shared libraries.

From the docs:

-buildmode=c-shared
Build the listed main packages, plus all packages that they
import, into C shared libraries. The only callable symbols will
be those functions exported using a cgo //export comment.
Non-main packages are ignored.

As we can see, we have to put these functions in a main package in order to export them to C. It'd be nice to leverage godoc for displaying documentation in these kinds of packages, too.

[dmitshur]

The only callable symbols will be those functions exported using a cgo //export comment.

Do you know if those functions—in addition to having cgo //export comment—also need to be exported? If not, godoc will not be very helpful, since it doesn't show unexported symbols. It'd need to both show documentation for main package and include unexported symbols.

[mjmac]

No, they don't need to be exported. But I don't see why that would make godoc unhelpful. For those functions which are both exported to C and follow the Go exporting convention, godoc could show documentation for those functions. Functions which don't follow the Go exporting convention would not be included in the default doc output, just as it is now.

For example, here is some code I'm working on (with an unexported function I just made up):

// DaosFileSystemReadDir reads the contents of a directory and passes the
// found dirent info to the supplied callback.
//export DaosFileSystemReadDir
func DaosFileSystemReadDir(/*a bunch of params*/) C.int {
        ...
        return 0
}

//export voidyMcVoidVoid
func voidyMcVoidVoid() {
        return
}

This results in a generated .h file like the following:

// DaosFileSystemReadDir reads the contents of a directory and passes the
// found dirent info to the supplied callback.

extern int DaosFileSystemReadDir(/*a bunch of params*/);

extern void voidyMcVoidVoid();

... So it's not required, but I still think it's potentially useful. I guess the alternative is to embed doxygen comments in comments that will end up in the headers, but ugh.