Feature Request: Make godoc support @arg (like @param in doxygen)?

[Alex Jin]

godoc is simple and easy to use, but if it supported @arg, the generated document would be more clear.

[Aaron France]

I know exactly who will poo-poo this but I totally agree with it. Documentation should have very clear and concise ways to document individual parameters and also return types. See Doxygen, Sphinx etc.

Regards,
Aaron

On Tue, Jun 18, 2013 at 8:56 AM, Alex Jin <toal...@gmail.com> wrote:

godoc is simple and easy to use, but if it supported @arg, the generated document would be more clear.

--
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.
 
 

[Alex Jin]

Right. When I write C/C++ code, I always follow the doxygen rule, and a very beautiful document could be generated from my source code. Actually, "go build" supports some tags/hints, i.e."// +build linux,amd64". We should make "go doc" support some tags/hints as well.

在 2013年6月18日星期二UTC+8下午3时58分18秒，Aaron France写道：

[minux]

On Tue, Jun 18, 2013 at 4:05 PM, Alex Jin <toal...@gmail.com> wrote:
> Right. When I write C/C++ code, I always follow the doxygen rule, and a very
> beautiful document could be generated from my source code. Actually, "go
> build" supports some tags/hints, i.e."// +build linux,amd64". We should make
> "go doc" support some tags/hints as well.

the fact that the go tool supports build tags is irrelevant to this issue.

i'm sure this has been discussed numerous times on this mailing list, please
search the archive.

[Kamil Kisiel]

I don't like the idea of having additional markup for the documentation, I think it just creates unnecessary visual noise in the source code.

However, what I think would be interesting to try would be to emphasize the names of function arguments and return values in the HTML documentation. 

[Kyle Lemons]

I think there is some middle ground here.

If we come up with a heuristic that is sensible and doesn't clutter the code with markup, you might be able to teach godoc about the fields.

Just as a straw man:

http://golang.org/src/pkg/text/tabwriter/tabwriter.go?s=6891:6997#L158

If you have an indented line that starts with the name of a parameter, assume that the rest of the line (and any subsequent lines whose indentation matches) documents the parameter.

This could allow godoc to e.g. allow hovering over the parameter name to show its documentation (even in the table of contents) and could provide more information for things like gocode.  The HTML representation could render the fields as a table and include the type (known from the soruce).  It doesn't add any markup to existing code, (hopefully) doesn't break existing documentation, and might have the long-term effect of making function documentation more consistent.

[Rémy Oudompheng]

Adding weird keywords in the middle of sentences doesn't make it
concise or clear.

The goal of documentation is not to make comments accessible to
machines but making source code accessible to humans.

There are less intrusive ways to emphasize that a word is actually a
variable name, like putting it between punctuation signs as it's done
in a few documentation or literate programming systems.

Rémy.


2013/6/18, Aaron France <aaron.l...@gmail.com>:

[Alex Jin]

Thanks for your input, I got it.

在 2013年6月19日星期三UTC+8上午4时32分07秒，Kyle Lemons写道：

[Sam Harwell]

Documentation can either be plain text, or can have an officially defined way to reference elements in code. Plain text reads like sentences, which according to the documentation at golang.org is a good thing. Unfortunately, the current design makes all of the following difficult to impossible:

 

1.       Parameter hints in an IDE

2.       Automatic rename refactoring algorithms which update the corresponding documentation without worrying about arbitrarily replacing unrelated text that happens to use the same word

3.       Fully cross-linked documentation

 

The online documentation for Go packages isn’t the most unpleasant I’ve had to use (that goes to a company whose NDA prevents me from publicly stating a negative review of their documentation, a decision I’m convinced is in place because they know how bad it is). Nevertheless, it was a frustrating experience and the godoc limitations, along with rationale suggesting many frustrating portions were by-design and unlikely to ever change, finally became the overall #2 reason we stopped pursuing Go for internal development (we were previously working on a Go target for ANTLR 4).

 

--

Sam Harwell

Owner, Lead Developer

http://tunnelvisionlabs.com

[Robert Johnstone]

I suspect that the difference of opinion here is related to whether users are generally reading documentation as part of the source code, or using a browser.  I've found documentation much easier to read in the source code than other languages, where the mark-up does reduce readability.  However, it is also fair to say that the online documentation contains fewer features than other languages.

Given the general reticence to add features, proposals for modifications to godoc will need to be unobtrusive.  I believe that Kyle is on the right track.

[Laurent Moussault]

On Wednesday, June 19, 2013 4:23:49 PM UTC+2, Sam Harwell wrote:

Documentation can either be plain text, or can have an officially defined way to reference elements in code. Plain text reads like sentences, which according to the documentation at golang.org is a good thing. Unfortunately, the current design makes all of the following difficult to impossible:

1.       Parameter hints in an IDE

2.       Automatic rename refactoring algorithms which update the corresponding documentation without worrying about arbitrarily replacing unrelated text that happens to use the same word

3.       Fully cross-linked documentation

At least point 2, and probably also 3, can be solved by using the solution suggested by Rémy Oudompheng: keep the current way of having one or two short sentences describing the function, and just put quotes around argument names. 

This is what was done for the language Eiffel, and the documentation was a pleasure both to read and write.

Concerning point 1, I prefer to use explicit arguments names. Having a description for each argument always lead to many repetitions and longer documentation, and makes it easier to overlook important information.

It's also more annoying to write, which often leads to missing documentation, IMHO.

Finally, we don't need to wait for godoc to support it: if we can all agree to put quotes or some other punctuation around argument names, it already make renaming easier, with a simple regexp.

-- drakmaniso

[Kamil Kisiel]

I think it's also worth keeping in mind that keeping the documentation simple makes it easier to write as well. It also keeps things simple since there's fewer possible variations on the types of comments. In large codebase you often get varying degrees of fragmentation depending on what markup features the author of a function decides to use. It makes it harder to achieve a uniform style. 

[Jeremy McAnally]

Why not use something like TomDoc?  It's easy to read and parsable: http://tomdoc.org

-jm

--

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.
 
 

--
http://jeremymcanally.com/

Positivity every morning: http://goodmorninginterwebs.com

Bowties, ties, and more: http://wickhamhousebrand.com

[Alex Jin]

I agree with you for all your input.

在 2013年6月19日星期三UTC+8下午10时23分49秒，Sam Harwell写道：

[Alex Jin]

Current godoc takes plain text (sentences), some of them are long sentences, which could be a barrier for international development, because many people's mother languages are not English. Although they could read English, but it would take them more time. Even for native English speaking people, they prefer reading formatted documents to long sentences. The theory is true for resume/cv/email as well. When you read a resume/cv/email, you would hate to read long sentences. Instead, you would prefer to read broken down items, like 1) xxx; 2) xxx; 3)xxx.

在 2013年6月20日星期四UTC+8上午12时20分01秒，Kamil Kisiel写道：

[Kamil Kisiel]

I can think of a few reasons that immediately come up:

The public / internal distinction is unnecessary since that's already taken care of by the language.

The testing package already provides a (superior) way to define examples.

The signature portion is also unnecessary for Go code, since that can be extracted from the function itself.

The only part that seems remotely useful for Go code is the arguments and returns sections, and those can already be covered by simpler proposals like the one Kyle made elsewhere in this thread.

[Kyle Lemons]

On Wed, Jun 19, 2013 at 8:50 AM, Jeremy McAnally <jeremym...@gmail.com> wrote:

Why not use something like TomDoc?  It's easy to read and parsable: http://tomdoc.org

All of the MUST's in that specification add more complexity over what we have in godoc.  You can make generally fine-looking godoc documentation without having to have a spec open for reference, without even knowing what heuristics it has.  The proposal I made above is quite similar to the arguments parsing in tomdoc, except that it's already used by some functions/methods in the standard library and it isn't so rigid as to have to be prefixed by an "Arguments" section header.  In general, I think rigid tomdoc-style documentation would wind up being many more lines than necessary in most cases, and make people even less likely to spend the time to write good documentation.

[Jeremy McAnally]

The specificity in the spec is so that machine parsers know what to expect.  It's a good thing.  Otherwise, you end up with ambiguity and badly parsed docs.  I hardly feel like one extra line is going to keep people from writing documentation, but perhaps you're right about that.

But the critiques here of the spec are kind off a bit.  Public/internal is still relevant in Go, but even so, the spec says you SHOULD use it, not that it's required.  You could just leave that off in a language like Go and have it automatically populated.

The testing package's example stuff is great, but it's not inline with documentation.  The whole point of this thread is figuring out a way to document things  in a readable fashion without a ton a syntax and extra stuff right?  I don't want to hunt around in 2 other files to figure out how to use a function.

The signature portion isn't used to specify what's expected syntactially but semantically.  That's great that you can extract the function signature from the code, but that's not documentation.  That doesn't tell me what sort of strings I should give to a function, for example; does it want XML or JSON or a specific structure of JSON or what?  (Poor example I know but you get what I mean)  That's what that section is for.

So, I don't feel like those are great reasons to reject TomDoc, really.  I understand, again, it's not for everyone.  But I've used it in a few languages now (Ruby, Coffeescript, C, and seen it used on Lua and PHP) and it's provided a nice general documentation format that's easily parseable and provides good structure for people to follow. :)

-jm

[Jeremy McAnally]

I meant in the files, which is often times how I'm looking at docs.  But maybe I'm weird for digging around in the source. ;)

-jm

On Thu, Jun 20, 2013 at 12:01 PM, Islan Dberry <islan...@ymail.com> wrote:

On Thursday, June 20, 2013 8:43:35 AM UTC-7, Jeremy McAnally wrote:

The testing package's example stuff is great, but it's not inline with documentation.  The whole point of this thread is figuring out a way to document things  in a readable fashion without a ton a syntax and extra stuff right?  I don't want to hunt around in 2 other files to figure out how to use a function.

The examples are displayed inline with the documentation. See http://golang.org/pkg/bytes/#Buffer for an example.

--
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.
 
 

[Sam Harwell]

The primary limitations of godoc that I’ve encountered center around the lack of any framework to support links from words in the documentation to actual code elements, necessary both for automatically cross-linked documentation and accurate, reliable IDE-based refactoring tools.

 

TomDoc suffers from two problems:

 

1.       TomDoc is written with a different language in mind (Ruby), and was designed to address specific concerns, limitations, and documentation requirements of that language. To be absolutely fair (especially since you said “like TomDoc”), support for some of these items could simply be omitted from an implementation targeting Go.

2.       More importantly, TomDoc does not address the concerns I mentioned above. For example, in the example for Class/Module Documentation you see the following text:

# Public: Various methods useful for performing mathematical operations.
# All methods are module methods and should be called on the Math module.

The Math module reference should me marked in some way such that “Find References” for the Math module identifies this reference consistently and accurately.

 

Javadoc supports referencing some code elements, but suffers from its own problems.

 

1.       The {@link …} syntax is sufficiently verbose that no one wants to use it.

2.       The {@link …} syntax does not allow references to method parameters, so you have to use {@code parameterName} which once again loses the ability to link the reference to the parameter definition.

3.       The {@link …} syntax only works within Javadoc comments, which are only allowed in specific locations. Specifically, Javadoc comments are not allowed within a method body, so you can never have a comment within a method body that references a local variable by name, where a Rename refactoring operation on that local variable will silently, consistently, and accurately update references to the variable from comments within the method.

 

I strongly feel that the semantic rules of documentation should meet several requirements to address the needs of both users and tools.

 

1.       The syntax needs to be simple, easy-to-type, and unobtrusive when reading the raw comment text. As a simple example, most users would agree that Markdown code syntax `text` is better than Javadoc’s {@code text} and C#’s <c>text</c> on all of these measures.

2.       The syntax needs to be usable from any comment in the language, not restricted to particular comments in particular locations. This requirement is fundamental for proper IDE support.

 

While I have not created a complete specification for documentation, the following rules may serve as some interesting food for thought.

 

1.       References to named semantic elements of go code within comments could be written with `backticks`.

2.       Which a comment appears within a method body containing an elements in `backticks`, the identifier in `backticks` is resolved as though it appeared at the end of the line following the comment.

3.       When a comment appears outside of a method body and immediately precedes a code element Foo and the comment contains an element in `backticks`, the identifier in `backticks` is resolved as though it appeared on the first line of the body of Foo.

4.       When a comment appears outside of a method body and does not immediately precede a code element, an identifier in `backticks` is resolved as though it appears on the line following the comment.

 

If the go language designers and/or community are interested in truly attacking this problem, I would be delighted to provide feedback on the suitability of the final design to meet the needs of automated tools (refactoring and analysis) within an IDE.

 

--

Sam Harwell

Owner, Lead Developer

http://tunnelvisionlabs.com

 

[Antoine Grondin]

In my short experience with Go, I've found that the documentation is especially good because it is terse.

For my own work, I've adopted the `backtick` style of Markdown when I write something referring to code.  Markdown looks nice in plaintext.  Adding some style to Markdown docs should also be trivial, if one so desires.

[Kevin Gillette]

On Tuesday, June 18, 2013 2:32:07 PM UTC-6, Kyle Lemons wrote:

If you have an indented line that starts with the name of a parameter, assume that the rest of the line (and any subsequent lines whose indentation matches) documents the parameter.

I think that's reasonable as a convention, but Go programmers should be dissuaded from using that style except for particularly complex parameters (and if they're so complex, perhaps the API should be simplified). Nonetheless, there are a few unavoidable cases where your suggestion of indented parameter documentation is the best approach, though I think we should avoid going with the typical doxygen approach in which even benign and trivial parameters are documented, "just because".

I think it's usually enough for godoc to recognize and highlight/inter-link parameter names at the beginning of sentences in function comments, exported field and method names in type comments, and package scoped exported and qualified names (such as Type and Type.Field) in all exported comments. The chance of these colliding with the natural language content of comments is unlikely ('x' is not a word, and if you have use 'the' as an identifier, don't expect anybody to use your code) -- the only particularly likely collision would be with parameters named 'a'. On the plus side, this means no additional syntax is needed (and thus the comment source would never need to be 'interpreted' by human eyes). The downside is there may be a rather occasional (but always harmless) false positive.

An example of this heuristic when applied to os.Create documentation would be:

func Create(name string) (file *File, err error)

Create creates the named file mode 0666 (before umask), truncating it if it already exists. If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR. If there is an error, it will be of type *PathError.

The names recognized by the above suggested heuristic (which is compatible with Kyle's) are displayed in bold. The word 'file' is not recognized since it does not appear at the beginning of a sentence. Aside from cross-linking, I personally feel that Go documentation is excellent enough and Go programmers are competent enough that any additional "assistance" in this regard may be distracting (in much the same way as many gophers feel about syntax highlighting).

[Sam Harwell]

False positives are not harmless during a refactoring operation. You may not use (or even like) automated refactoring tools, but you should be aware that the convention described below permanently incapacitates any future attempt at creating a true automated refactoring tool for Go code.

 

--

Sam Harwell

Owner, Lead Developer

http://tunnelvisionlabs.com

 

--

[Kyle Lemons]

On Fri, Jun 21, 2013 at 6:33 AM, Sam Harwell <s...@tunnelvisionlabs.com> wrote:

False positives are not harmless during a refactoring operation. You may not use (or even like) automated refactoring tools, but you should be aware that the convention described below permanently incapacitates any future attempt at creating a true automated refactoring tool for Go code.

If you make everyone use some crazy `{@param type} description` syntax, you don't even need to worry about updating comments when you refactor because they won't be written in the first place ;-).  If you change an exported type or identifier name too, do you want the refactor tool to scrub every package on godoc.org for doc references to the type name and update them as well?  No refactoring tool is ever going to be perfect, and it's not obvious to me whether one that just does an "okay" job at rewriting comments is better than one that explicitly does not do that (so you, the person with the most knowledge about what comments need to be updated, can do so).

It's also worth pointing out that writing documentation that is unlikely to get stale is one part of good code hygiene, so it's probably not necessary to use param and type names in the documentation if you can convey the point without them (the types, in particular, are right there for a function definition and are now cross-linked).

[Nate Finch]

I agree with Kyle and Kevin. Keeping the documentation standard simple is one of the reasons why so many go packages are well documented. It is also why they're so much more readable than other more strictly defined documentation standards. Finally, I think it's a really good point that if your function is well thought out, and the argument names and types are good enough, you probably don't need to refer to them specifically by name. In other languages people don't even *have* types, and they do ok. We're one step up by giving an additional hint of showing the type we expect.

I really don't want people to (for example) be tempted to document the w and r parameters of io.Copy(r Reader, w Writer). It adds unnecessary clutter that just makes the documentation worse. I have done this myself in other languages, if the IDE auto-generates lines for documentation of the parameters, my first inclination is "oh, I should put a description in there...."  even if that description is "r is the reader from which you wish to copy data". Well, duh, thanks. It takes a lot more effort and more than a little bit of wincing to delete those auto-generated lines. 

I think leaving it as-is, is fine. If you need to document a parameter, you can indent it and get monospacing to offset it from the rest of the documentation. That's usually more than enough.

[gauravk]

Comparing the documentation of Go http package documentation at http://golang.org/pkg/net/http/ to well used Apache http libraries:

http://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/

http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/

I find Apache lib docs to be totally unwieldy. There is no way one can get handle of apache lib in reasonable time despite documentation of all method parameters. On the other hand Go's http docs are in my opinion excellent and cover most of the important stuff that matters.

So I do not see any additional complexity to godoc will bring any more comprehensibility to Go code documentation.

[Kamil Kisiel]

That's a great example of why I dislike the style of commenting being proposed here. You end up with the tendency to document every parameter in a useless fashion. For example:

Parameters:

buffer - the session input buffer.

responseFactory - the HTTP response factory.

params - HTTP parameters.

The annotated documentation tells me nothing I couldn't gather from the function signature and description, and just takes up space on the page.

[Kevin Gillette]

I agree that IDE support for documentation generation can actually be harmful -- if the tool is good enough to generate documentation and put it in the source code, then really the source should be left alone and that same tool should generate necessary documentation on the fly.