I think this is a great idea, and something that could hugely improve semi-automated documentation sites, man pages, etc. I also think that you could get a lot

I think this is a great idea, and something that could hugely improve semi-automated documentation sites, man pages, etc. I also think that you could get a lot of people to agree that it is a great idea, and STILL have a lot of trouble enforcing it in a project without very rigid code review policies and very good linting rules.