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.
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).
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.
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.
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.
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.
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.
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...
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...
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.
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.
That is a totally valid option. That’s a successful model for things like DataStax, RedisLabs, RedHat, and on and on. If you’re wondering how a company makes money just selling open source, this is it.
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.
Something that could be helpful and clarify the intention, is to explicitly license those artifacts under a different, more open (Apache/MIT/etc.) license.
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...
[2]: https://stackoverflow.com/a/24385103
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...
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:
So if you're shipping docs generated by NaturalDocs to customers then you are shipping AGPLv3 and need to follow the license requirements.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.