5 ms·

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

by 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...

by usrme 5y ago

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...