![]() 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 Which a comment appears within a method body containing an elements in `backticks`, the identifier in `backticks` is resolved as though it appearedĪt the end of the line following the comment.ģ. References to named semantic elements of go code within comments could be written with `backticks`.Ģ. While I have not created a complete specification for documentation, the following rules may serve as some interesting food for thought.ġ. The syntax needs to be usable from any comment in the language, not restricted to particular comments in particular locations. As a simple example, most users would agree that MarkdownĬode syntax `text` is better than Javadoc’s text} and C#’s text on all of these measures.Ģ. The syntax needs to be simple, easy-to-type, and unobtrusive when reading the raw comment text. I strongly feel that the semantic rules of documentation should meet several requirements to address the needs of both users and tools.ġ. To the variable from comments within the method. 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 The …} syntax only works within Javadoc comments, which are only allowed in specific locations. Link the reference to the parameter definition.ģ. The …} syntax does not allow references to method parameters, so you have to use parameterName} which once again loses the ability to The …} syntax is sufficiently verbose that no one wants to use it.Ģ. Javadoc supports referencing some code elements, but suffers from its own problems.ġ. The Math module reference should me marked in some way such that “Find References” for the Math module identifies this reference consistently and accurately. # All methods are module methods and should be called on the Math module. # Public: Various methods useful for performing mathematical operations. For example, in the example for Class/Module Documentation you see the following More importantly, TomDoc does not address the concerns I mentioned above. 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.Ģ. TomDoc is written with a different language in mind (Ruby), and was designed to address specific concerns, limitations, and documentation requirements 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Įlements, necessary both for automatically cross-linked documentation and accurate, reliable IDE-based refactoring tools.ġ. 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). Nevertheless, it was a frustrating experience and the godoc limitations, along with rationale suggesting many frustrating portions were by-design and unlikely Review of their documentation, a decision I’m convinced is in place because they know how bad it is). 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 Automatic rename refactoring algorithms which update the corresponding documentation without worrying about arbitrarily replacing unrelated text that Unfortunately, the current design makes all of the following difficult to impossible:Ģ. To the documentation at is a good thing. Plain text reads like sentences, which according " can either be plain text, or can have an officially defined way to reference elements in code. "doxdocgen.c.factoryMethodText ": "Create a should be split according to their casing. Smart text snippet for factory methods/functions. The prefix that is used for each comment line except for first and last.
0 Comments
Leave a Reply. |