NaturalDocs: Plain English code documentation
naturaldocs.org
naturaldocs.org
// Function: Multiply
// Multiplies two integers and returns the result.
int Multiply (int x, int y)
{ return x * y; }
/** Multiplies two integers and returns the result. */
int Multiply (int x, int y)
{ return x * y; }
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;
* 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.
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.
---
[1]: https://github.com/google/styleguide/blob/gh-pages/pyguide.m...
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.
I personally hate them because of the amount of noisy fluff they bring.
This looks similar to Markdown and APT but nothing I found is as capable as AsciiDoc...
/// 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 { /* ... */ }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.
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.
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.
And for the record, I think this is dumb. But I’m describing the reality of what I have to deal with so folks making can understand.
There’s 2 basic routes here:
1) offer it for under 1k per seat through a distributor. Then it’s like buying an IDE. You won’t pick up a company-wide deployment, but team by team.
2) Have a commercial offering listed with pricing. Then have sales and legal folks.
The sales will be negotiating the price down by volume. The legal will go back and forth on the contract. Companies will require different language based on their requirements and legal culture. It’s not uncommon for them to require OSS indemnification. That can mean absorbing their risk if you don’t own 100% of the code. You’re basically their insurance policy on OSS violations.
Also, usually this includes some kind of (often useless) support agreement. Pricing can be tiered by response time (24x7, next business day, and so on.). It’s not a big deal on something non operational like this.
For the indemnification, the legal department doesn’t trust their developers (or contract developers) to take a shortcut, not pay attention, or whatever and expose them to a claim.
If I didn’t build it from scratch and didn’t want to start a company, that’s the route I would go.