5 ms·

NaturalDocs: Plain English code documentation

67 points by childintime 5y ago

billconan 5y ago
how to handle c preprocessor using this tool?
usrme 5y ago
Since it's been around since 2003, I'm curious to know how many projects out there are using it. Would be great if there are some open source examples available as well. I mostly stick to Python, so I'm most familiar with the Google docstring format[1], but seeing as there are other ones[2] as well aren't those usable for other languages too? Seems to be the case of yet another "standard", though since this is such an old project I may out of my depth in saying that. --- [1]: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings https://github.com/google/styleguide/blob/gh-pages/pyguide.m... [2]: https://stackoverflow.com/a/24385103 https://stackoverflow.com/a/24385103
- SavantIdiot 5y ago
  I joined a project that used it back in 2014. What I found was that the documentation ended up being about as useful as reading the header files, and less useful once you open the code in an IDE that allows semantic browsing. OTOH, if someone does take the time to document the header files, they blow up in size significantly. I don't like it. Better to just keep documentation up to date and keep the two separate. Comments should be concise, documentation should be more verbose, IMHO.
  - ehutch79 5y ago
    or worse, the comments arn't kept up to date, and now life would actually have been easier just looking at the function definitions without comments
  - childintime 5y ago
    I agree with your point, comments easily grow out of date, but I see competing tools like doxygen or javadoc being used. Do you have any experience with those? I personally hate them because of the amount of noisy fluff they bring.
    - SavantIdiot 5y ago
      I soured on the idea (more work, ROI?) and never used them, but when I see pages like Webpack, Bootstrap and Python docs, I drool over their well-designed, easily cross-referenced doc system and wonder what they use. Someday...
jasonpeacock 5y ago
Be sure to carefully review the license, especially if you're a business user: https://www.naturaldocs.org/documentation/#File:Engine/Resources/License/License.txt https://www.naturaldocs.org/documentation/#File:Engine/Resou... It's AGLPv3, which is usually OK for development tools because you aren't modifying/shipping them to customers - only the output/artifacts (a la GCC). But NaturalDocs will inject AGPLv3 artifacts (JS, CSS, etc.) into your doc output: Portions of Natural Docs are automatically included with generated documentation in order to help it function, such as JavaScript, CSS, and image files. These included files retain the copyright and licensing terms of Natural Docs, but those terms do not apply to the remainder of the generated documentation. All other generated documentation files remain under the copyright and distribution terms decided by its author. So if you're shipping docs generated by NaturalDocs to customers then you are shipping AGPLv3 and need to follow the license requirements.
- suyash 5y ago
  Can't touch this now even with a 40 foot pole, back to good old JavaDocs I go :)
- NaturalDocsGreg 5y ago
  Hi, I'm the author. That language was intended to specifically say that Natural Docs' license doesn't affect the rest of the documentation, let alone the project it's documenting, but without forfeiting my copyright to those particular files. If there's language that I could include to make this even clearer I'd be happy to. In my opinion shipping code plus documentation generated by Natural Docs does not cause the code to fall under the AGPL, as you are bundling it rather than making a derivation of it. You could argue that the documentation is a derivation of it, but that's what I try to explicitly disavow above.
  - salmo 5y ago
    Just FYI: This makes total sense. But that’s not how corporate lawyers read it in my experience. I think it’s a) poor legal understanding of software and b) AGPLv3 signaling litigiousness. And in some regards, even if the lawyer doesn’t fall in A, they know courts may. Their job is risk management. If I submit, they’ll tell me to use a MIT, BSD, Apache 2.0, etc alternative or buy something and suck it up. Also they have a bunch of these to review, plus contracts, etc. so understandably have no time to debate.
transfire 5y ago
Reminds me of TomDoc.
rendall 5y ago
One critique is that the documenting must duplicate the name and type when it's right there. e.g. // Function: Multiply // Multiplies two integers and returns the result. int Multiply (int x, int y) { return x * y; } JSDoc, by contrast, uses the code itself and it's not necessary to duplicate the name. /** Multiplies two integers and returns the result. */ int Multiply (int x, int y) { return x * y; } I might recommend the addition of this feature, if I understood the intent of the project correctly.
- NaturalDocsGreg 5y ago
  For languages that have a custom parser written for it (currently only C#) you can absolutely omit the first line. For all other languages it needs the line to know what its documenting and how to include the prototype since it's relying on a more generic parser. This lets it work with almost any language, and you can even add support for new languages just by editing a text file, but it admittedly makes it more verbose.
Emil695 5y ago
[dead]
cherryblossom00 5y ago
This reminds me of Swift/Xcode's documentation comments: /// Does something. /// /// - Parameters: /// - bar: A description for bar. /// - baz: A description for baz. /// /// - Returns: Something fancy. /// - Throws: Throws `SomeErrorType` if `bar` is invalid. func foo(bar: String, baz: Int) throws -> Bool { /* ... */ }
dusted 5y ago
I hate these "languages implemented in comments" jsdoc is another one. They force you to write more comment code (sometimes the comment will be longer than the actual function), they force you to repeat yourself, but with ever so slightly more information and different syntax (but this time, forget about syntax checking or highlighting!). They disconnect actual code from the documentation, even if they're "right there next to it" it's annoying to have to edit two different places, and possible to forget to update the comment. I'd probably accept one that scrapes comments, but has no syntax, except maybe something _VERY_ short to enable/disable the scraping of an individual comment. I'd prefer it if the language allowed me to write this metadata directly into the syntax, so that it is natural flow to include the explanations where they are needed. One thing I found interesting and nice about Objective-C syntax was the way function declarations made them self-explanatory. You never needed think twice about what the parameter was for (assuming the function author did a slight effort in naming). (int) Multiply: (int)x with: (int)y result = Multiply: 23 with 3; (int) Subtract: (int)a from: (int)b andMultiplyBy: (int)c result = Subtract: 1 from: 4 and MultiplyBy: 2;
- pydry 5y ago
  I dislike them too. Not only because it's an inducement to duplicate everything, but because the documentation usually loses important context that * Helps you locate it by knowing what you want to do but without e.g. knowing key words. * Lets you know which APIs to use it with. * Lets you know how to chose between sounding seeming APIs. All of this context can be added but then you add it everywhere and suddenly your comments are ballooning in size and you're duplicating the same context multiple times across multiple methods.
  - tpoacher 5y ago
    Obviously this package is not python specific, and what I'm about to say is only useful for languages who treat documentation the same way as python, but! One thing I like about python is that the documentation for any function or class is actually part of the object (held in its __doc__ attribute), and the whole 'triple-quoted string above the function' convention is actually just syntactic sugar, which assigns that string to the object's __doc__ attribute. The beauty of this is that you can completely externalise documentation into another package, if you really wanted to, and attach it to your objects separately! This means you can keep documentation separate, keeping your code as free of comments as you like. One nice thing about this, is that it allows you to maintain two 'categories' of documentation: the user-oriented documentation goes into the external file, whereas any 'developer-oriented' documentation which is explicitly for the maintainer's benefit while looking at the code, can appear directly in the source, and you can be sure that this will be safely removed from the user-oriented documentation later.
ivolimmen 5y ago
I am using AsciiDoc / AsciiDoctor.org as my format for documentation. It is really extensive and broad what you can do and how you can make nice formatted documents. This looks similar to Markdown and APT but nothing I found is as capable as AsciiDoc...

67 points by childintime 5y ago

how to handle c preprocessor using this tool?

Since it's been around since 2003, I'm curious to know how many projects out there are using it. Would be great if there are some open source examples available as well. I mostly stick to Python, so I'm most familiar with the Google docstring format[1], but seeing as there are other ones[2] as well aren't those usable for other languages too? Seems to be the case of yet another "standard", though since this is such an old project I may out of my depth in saying that. --- [1]: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings https://github.com/google/styleguide/blob/gh-pages/pyguide.m... [2]: https://stackoverflow.com/a/24385103 https://stackoverflow.com/a/24385103

SavantIdiot 5y ago
I joined a project that used it back in 2014. What I found was that the documentation ended up being about as useful as reading the header files, and less useful once you open the code in an IDE that allows semantic browsing. OTOH, if someone does take the time to document the header files, they blow up in size significantly. I don't like it. Better to just keep documentation up to date and keep the two separate. Comments should be concise, documentation should be more verbose, IMHO.
- ehutch79 5y ago
  or worse, the comments arn't kept up to date, and now life would actually have been easier just looking at the function definitions without comments
- childintime 5y ago
  I agree with your point, comments easily grow out of date, but I see competing tools like doxygen or javadoc being used. Do you have any experience with those? I personally hate them because of the amount of noisy fluff they bring.
  - SavantIdiot 5y ago
    I soured on the idea (more work, ROI?) and never used them, but when I see pages like Webpack, Bootstrap and Python docs, I drool over their well-designed, easily cross-referenced doc system and wonder what they use. Someday...

jasonpeacock 5y ago

Be sure to carefully review the license, especially if you're a business user: https://www.naturaldocs.org/documentation/#File:Engine/Resources/License/License.txt https://www.naturaldocs.org/documentation/#File:Engine/Resou... It's AGLPv3, which is usually OK for development tools because you aren't modifying/shipping them to customers - only the output/artifacts (a la GCC). But NaturalDocs will inject AGPLv3 artifacts (JS, CSS, etc.) into your doc output: Portions of Natural Docs are automatically included with generated documentation in order to help it function, such as JavaScript, CSS, and image files. These included files retain the copyright and licensing terms of Natural Docs, but those terms do not apply to the remainder of the generated documentation. All other generated documentation files remain under the copyright and distribution terms decided by its author. So if you're shipping docs generated by NaturalDocs to customers then you are shipping AGPLv3 and need to follow the license requirements.

suyash 5y ago
Can't touch this now even with a 40 foot pole, back to good old JavaDocs I go :)
NaturalDocsGreg 5y ago
Hi, I'm the author. That language was intended to specifically say that Natural Docs' license doesn't affect the rest of the documentation, let alone the project it's documenting, but without forfeiting my copyright to those particular files. If there's language that I could include to make this even clearer I'd be happy to. In my opinion shipping code plus documentation generated by Natural Docs does not cause the code to fall under the AGPL, as you are bundling it rather than making a derivation of it. You could argue that the documentation is a derivation of it, but that's what I try to explicitly disavow above.
- salmo 5y ago
  Just FYI: This makes total sense. But that’s not how corporate lawyers read it in my experience. I think it’s a) poor legal understanding of software and b) AGPLv3 signaling litigiousness. And in some regards, even if the lawyer doesn’t fall in A, they know courts may. Their job is risk management. If I submit, they’ll tell me to use a MIT, BSD, Apache 2.0, etc alternative or buy something and suck it up. Also they have a bunch of these to review, plus contracts, etc. so understandably have no time to debate.

transfire 5y ago

Reminds me of TomDoc.

rendall 5y ago

One critique is that the documenting must duplicate the name and type when it's right there. e.g. // Function: Multiply // Multiplies two integers and returns the result. int Multiply (int x, int y) { return x * y; } JSDoc, by contrast, uses the code itself and it's not necessary to duplicate the name. /** Multiplies two integers and returns the result. */ int Multiply (int x, int y) { return x * y; } I might recommend the addition of this feature, if I understood the intent of the project correctly.

NaturalDocsGreg 5y ago
For languages that have a custom parser written for it (currently only C#) you can absolutely omit the first line. For all other languages it needs the line to know what its documenting and how to include the prototype since it's relying on a more generic parser. This lets it work with almost any language, and you can even add support for new languages just by editing a text file, but it admittedly makes it more verbose.

Emil695 5y ago

[dead]

cherryblossom00 5y ago

This reminds me of Swift/Xcode's documentation comments: /// Does something. /// /// - Parameters: /// - bar: A description for bar. /// - baz: A description for baz. /// /// - Returns: Something fancy. /// - Throws: Throws `SomeErrorType` if `bar` is invalid. func foo(bar: String, baz: Int) throws -> Bool { /* ... */ }

dusted 5y ago

I hate these "languages implemented in comments" jsdoc is another one. They force you to write more comment code (sometimes the comment will be longer than the actual function), they force you to repeat yourself, but with ever so slightly more information and different syntax (but this time, forget about syntax checking or highlighting!). They disconnect actual code from the documentation, even if they're "right there next to it" it's annoying to have to edit two different places, and possible to forget to update the comment. I'd probably accept one that scrapes comments, but has no syntax, except maybe something _VERY_ short to enable/disable the scraping of an individual comment. I'd prefer it if the language allowed me to write this metadata directly into the syntax, so that it is natural flow to include the explanations where they are needed. One thing I found interesting and nice about Objective-C syntax was the way function declarations made them self-explanatory. You never needed think twice about what the parameter was for (assuming the function author did a slight effort in naming). (int) Multiply: (int)x with: (int)y result = Multiply: 23 with 3; (int) Subtract: (int)a from: (int)b andMultiplyBy: (int)c result = Subtract: 1 from: 4 and MultiplyBy: 2;

pydry 5y ago
I dislike them too. Not only because it's an inducement to duplicate everything, but because the documentation usually loses important context that * Helps you locate it by knowing what you want to do but without e.g. knowing key words. * Lets you know which APIs to use it with. * Lets you know how to chose between sounding seeming APIs. All of this context can be added but then you add it everywhere and suddenly your comments are ballooning in size and you're duplicating the same context multiple times across multiple methods.
- tpoacher 5y ago
  Obviously this package is not python specific, and what I'm about to say is only useful for languages who treat documentation the same way as python, but! One thing I like about python is that the documentation for any function or class is actually part of the object (held in its __doc__ attribute), and the whole 'triple-quoted string above the function' convention is actually just syntactic sugar, which assigns that string to the object's __doc__ attribute. The beauty of this is that you can completely externalise documentation into another package, if you really wanted to, and attach it to your objects separately! This means you can keep documentation separate, keeping your code as free of comments as you like. One nice thing about this, is that it allows you to maintain two 'categories' of documentation: the user-oriented documentation goes into the external file, whereas any 'developer-oriented' documentation which is explicitly for the maintainer's benefit while looking at the code, can appear directly in the source, and you can be sure that this will be safely removed from the user-oriented documentation later.

ivolimmen 5y ago

I am using AsciiDoc / AsciiDoctor.org as my format for documentation. It is really extensive and broad what you can do and how you can make nice formatted documents. This looks similar to Markdown and APT but nothing I found is as capable as AsciiDoc...