[HN Gopher] NaturalDocs: Plain English Code Documentation
___________________________________________________________________
NaturalDocs: Plain English Code Documentation
Author : childintime
Score : 23 points
Date : 2022-01-20 16:15 UTC (6 hours ago)
(HTM) web link (www.naturaldocs.org)
(TXT) w3m dump (www.naturaldocs.org)
| billconan wrote:
| how to handle c preprocessor using this tool?
| transfire wrote:
| Reminds me of TomDoc.
| usrme wrote:
| 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.m...
|
| [2]: https://stackoverflow.com/a/24385103
| SavantIdiot wrote:
| 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 wrote:
| 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 wrote:
| 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.
| jasonpeacock wrote:
| Be sure to carefully review the license, especially if you're a
| business user:
|
| 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 wrote:
| Can't touch this now even with a 40 foot pole, back to good old
| JavaDocs I go :)
| NaturalDocsGreg wrote:
| 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.
___________________________________________________________________
(page generated 2022-01-20 23:02 UTC)