|
Article Publishing
|
~ is some of golang documentation too terse |
Most of the golang docs are precise and well written. Some of the documentation is a little bit terse...
For example you'll find a function and it's only documentation is this:
"Sprintf formats according to a format specifier and returns the resulting string."
Okay, but, please elaborate! What pray tell is a format specifier and where do I find information on it? Indeed an experienced programmer will know it by heart. But that IMO is not an excuse to just take for granted that everyone knows what format specifiers are, and how many of them there are, and what valid format specifiers exist (who is to say they are the same as other languages, for example?).
Indeed if you sift through the documentation and go back to /pkg/fmt docs you can find all the format specifiers. It is in the docs, you just have to find it.... it's not always linked properly. if you have already been to the docs before and are just relooking something up, this is great as you can memorize the doc layouts and locations by heart. But again... it assumes programmers are super aspergers OCD types that memorize such...
Someone once jokingly called the GoLang docs "sparse" on twitter.
Short brief docs are very good if you are just looking to get on with programming and not waste time sifting through millions of lines of verbose rambling.. Indeed. But...
I am wondering if the reason is partially because of the tool being used to generate the documentation: docs written inside source files means that you try to not elaborate too much because if you do, your source file becomes bloated with text comments rather than code. Same issues occurred in for example the Synapse for Delphi documentation, which I found to be very terse and brief.
I'm not familiar with go documentation tool, and have not used it yet, so I don't really know the reasons and could be inaccurate about this.. But what seems to be happening here is something similar to the FPDoc vs PasDoc wars.... FPDoc is a documentation system that keeps documentation in a separate file, nothing in the source. PasDoc AFAIR was an inline documentation system. Both have their advantages: pasdoc style tools allow you to document the code right there and then without losing your concentration opening up obnoxious xml editors or such.
But I always find with every project that uses a embedded or inline documentation approach, the docs end up suffering in some areas as the documentation for some items is very terse and brief and doesn't go into enough detail or provide enough examples underneath.
On the other hand you have bloated documentation systems with hundreds of comments underneath by end users (such as the PHP documentation system) but that's also got advantages and disadvantages. I don't know what documentation generation system php uses on the source files itself, nor do I know the input parameters or files used, but specifically the online comment system is a double edged sword: you can get spammers, irrelevant or outdated comments, incorrect comments, etc.
Back to godoc and pasdoc and fpdoc discussion though: It's almost as if there needs to be a terse brief set of docs, and then another more verbose lengthy one. However this would make not so much sense as it's two copies of docs to maintain. I just find sometimes I want a nice brief documentation for a function, but other times I need the long drawn on PHP comment at the bottom of the page of a real world programmer saying "this function has this one caveat..." and then he goes on to document the function in his own words.
|
|