J.Ja
Discussion on:
View:
Show:
That looks like a neat tool, and certainly fills a humongous hole in the JavaScript development landscape. Now that being said, it is much more important *what* you document rather than *how* you document. All too often, JavaDocs are filled will little more than a walk through the class tree via reflection, and add little value other than syntactic reference. You have to document not just "how", but "why". Hopefully, tools like this (also it does seem like a rather clumsy process to use) will encourage developers to write documentation beyond "i is the variable to loop iterates through".
J.Ja
J.Ja
Avoid the trap of undocumentation. Your job is far from being over when you run a documentation generation tool -- it doesn't actually generate documentation, but just a basic scaffold for documentation. You need more.
I find that languages with the best documentation generation tools tend to suffer the most from "undocumentation".
I find that languages with the best documentation generation tools tend to suffer the most from "undocumentation".
There is something about those code generators, that typically do not do more than spit out a syntax reference, that gives the illusion of documentation. Granted, if you use verbose naming (as Wayne recommends, and I generally follow as well), it does do a fairly decent job to the end user... but it still gives little help to the coder who wants to know internal details like thread safety, or contextual details such as when to use it vs. a similar function, and so on. So far, my favorite documentation is Perl's, it is nearly 100% "why", and only somewhat "how". using those docs not only helps you write working code, but it helps you write good code. No code generator can do that.
J.Ja
J.Ja
Notice that some of the best software documentation in the world is in CPAN -- and Perl doesn't have doc generators of the sort you see in those languages that are plagued by tons of "undocumentation". Instead, what Perl provides is nothing to automatically create documentation, but excellent tools to format the documentation you write, for a number of different file types.
If you eliminate the drudgery of having to create the output document types for documentation, but avoid giving the illusion of automatically generated documentation content that you get with automatic syntax documentation generation tools, I think you'll get exactly what Perl has: the best documentation tools I've ever seen, in terms of encouraging good documentation by developers. Since that's really the end result we want, it trumps the whiz-bang automatic documentation tools of other languages like JavaDoc and RDoc.
If you eliminate the drudgery of having to create the output document types for documentation, but avoid giving the illusion of automatically generated documentation content that you get with automatic syntax documentation generation tools, I think you'll get exactly what Perl has: the best documentation tools I've ever seen, in terms of encouraging good documentation by developers. Since that's really the end result we want, it trumps the whiz-bang automatic documentation tools of other languages like JavaDoc and RDoc.
Oops, the @final indicates that this is the final value. The @exec indicates that the method is to be executed during the JSDoc pre-processor step.
To repeat a recommendation I constantly make, use self documenting code techniques in lieu of comments as much as possible.
From the example above, there is no reason to use names like "keybAlphaNumeric" and then describe what it really does. Use a name like IsAValidAlphabeticOrNumericInput and break the function into a separate validation function and error generating function - the "and" in the original comment is a prime indicator that this should be done to clarify the the purpose of the function.
Aggressively clarify code and the need for documentation greatly diminishes.
From the example above, there is no reason to use names like "keybAlphaNumeric" and then describe what it really does. Use a name like IsAValidAlphabeticOrNumericInput and break the function into a separate validation function and error generating function - the "and" in the original comment is a prime indicator that this should be done to clarify the the purpose of the function.
Aggressively clarify code and the need for documentation greatly diminishes.
I followed the instructions thoroughly but there is no jsdoc.pl anywhere. This is frustrating!
- Keyboard Shortcuts:
- Prev
- Next
- Toggle
