Writing Code Comments for Effective API Reference Documentation

Posted by Christopher Diggins, 4 January 2010 6:33 pm

Since I joined Autodesk, I have had the opportunity to work with multiple SDKs throughout the Media and Entertainment (M&E) division. I am working on trying to improve the consistency and effectiveness of our SDK documentation across various products. One step towards this is agreeing on a set of guidelines for developers writing code comments that are transfomed into SDK reference documentation.

I have written a draft document describing what I consider to be best practices for writing code comments, that are transformed into API documentation using doxygen. Most of the document is general enough though that it should apply to comments processed by other documentation generating tools such as Doc-o-matic and Sandcastle as well.

I am posting a link to the document here because I am interested in hearing any feedback from other developers about their thoughts regarding these guidelines, and to share there own suggestions for writing effective code comments.

You can find the document "Writing Code Comments for Effective API Reference Documentation" at http://docs.google.com/View?id=dgjz7z25_129f4sqrrdx.


1 Comment

Christopher Diggins

Posted 15 January 2010 4:35 pm

We do not have any plans in the short term to add more documentation to the existing SDK samples. For new SDK samples we are striving to improve our documentation.

Add Your Comment

You must be logged in to post a comment.

Please only report comments that are spam or abusive.