[SavantIdiot]

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.

[childintime]

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]

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

[ehutch79]

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