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