I don’t think inline documentation scales as well as we’d like it to.
For example, consider Ben Alman’s BBQ library It is littered with inline docs (for NaturalDocs) but he’s recently been reconsidering this decision to go with inline docs. It ends up making development a bit tougher.
I think APIs should be documented in HTML/Markdown/Wiki. It keeps the code clean and gives you plenty of flexibility to add examples, videos, whatever.
I do however, really enjoy the annotated source view that Docco provides.
I just did Modernizr’s source like this so you can take a look:
Paul Benjamin Irish
I don’t think inline documentation scales as well as we’d like it to.
For example, consider Ben Alman’s BBQ library It is littered with inline docs (for NaturalDocs) but he’s recently been reconsidering this decision to go with inline docs. It ends up making development a bit tougher.
I think APIs should be documented in HTML/Markdown/Wiki. It keeps the code clean and gives you plenty of flexibility to add examples, videos, whatever.
I do however, really enjoy the annotated source view that Docco provides.
I just did Modernizr’s source like this so you can take a look:
The annotated source of Modernizr