Go: proposal: cmd/godoc: parameter/return field

[mattn]

In sometimes, I hope to know the meaning of function parameters in source code. However, most of godoc(s) comment are just explaining abridgely like // XXX create Writer from w. This often makes confusing especially for non-english speakers. So I hope to add syntax to make documentation like doxygen or javadoc in godoc comment.

Note: I give you due warning, I don't mean that all of go codes must be complying this syntax. Just providing way to create useful documentation.

// CreateDocument create document file on the directory path.
// @param path Path to the directory to create the document file.
// @param mode Mode to switch Rich/Simple mode.
// @return filename created
// @return error when occured
func CreateDocument(path string, mode Mode) (string, error) {
   //...
}

godoc command generate html table tag from the parameter/return directives. I know that you have many different opinions about this. Someone doesn't like this syntax. And maybe it need more syntax is needed. However, this may be useful to read/write documentation, and know what the parameter/return value is meaning, I guess.

Thanks.

[ericlagergren]

Suggestion/question: couldn't go lint be changed to complain if explanations for the parameters are omitted?

[minux]

Possibly dup of #229 and see also #4118.

[mattn]

Revently, I deliver products written in Go for my customers with godoc documentation. The documentation is written in english currently. godoc is beautiful look to see documentation.

However all of programmers cannnot write english in the world. As I said in above, // XXX make bytes.Buffer from w often makes confusing in non-english speakers. If possibly, we have better to provide the way to write godoc for non-english people.

In additional, godoc accept to write in free style. So often, I forgot to add description of new parameters. As @ericlagergren said, varidator will be useful to check whether the documentation is broken.

[mattn]

I say again, I don't want to add complying. Just want to add extensible for the documentation. For example, This is one of the way to do.

$ godoc -html -formatter ./path/to/formatter .

[rsc]

There is a hook in the packages that godoc uses that can be used to turn all references to certain names into code font, so that parameters can be shown in a separate font. But it's unclear if that's sufficient for your needs.

We don't want to add explicit markup, like @param and @return, even optionally. It's important that doc comments read as ordinary comments, without needing to know about special syntax.

[minux]

I think godoc could definitely help more here.

For example, assuming the docs is not too long, that is, all the docs and
the function prototype are displayed in the screen, then we can make godoc
highlight the argument when the mouse pointer hovers over the name of the
argument in the docs.

However, this might not help if the argument name is too common a word, and
are "used" in the docs for purposes other than referring to the argument.

[ericlagergren]

@rsc this isn't my issue, but I'd appreciate having parameter names be in code.

[rsc]

As noted before, one of the first principles of godoc comments is to avoid markup like @param.