Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

This question already has an answer here:

I've seen a lot of different ways to [or not to] comment out the code, specially patterns on desciptions of function details and file purposes.

I'd like to know what is most used pattern to do that [I'm specially interested on documentation generators and their patterns]

share|improve this question

marked as duplicate by gnat, GlenH7, MichaelT, BЈовић, Dan Pichelman Jul 26 '13 at 16:22

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

3 Answers 3

up vote 7 down vote accepted

Numerous projects are using Doxygen, and I think you won't go wrong to pick that one as your choice. I've previously been involved in a portion of a much larger project that used Doxygen during their build process, do I didn't get into the actual doc generation part of the build, but adding the comments was easy and straight forward .

If your project is large with sub-systems written in different languages, then Doxygen is beneficial because of the many languages it supports: C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.

share|improve this answer
1  
That was my initial option. Doxygen style looks really interesting, but I like Doc-O-Matic, its native comments are really more friendly, when reading the source code. –  JulioC Oct 15 '10 at 6:20
    
+1, I'm really fond of Doxygen. If you take a few hours to really study its capabilities, it will pamper you and anyone else who has to use your code. –  Tim Post Oct 15 '10 at 10:03

I used to put effort into documenting code using these kind of automated documentation tools (doxygen, javadoc). However, I seem to find that the cost of creating and maintaining this kind of documentation was rarely justified by the benefits from having it. As long as your users can see the names/types of your function parameters.

I prefer to spend the time creating/maintaining examples and task focused documentation (how do I x?), as well as general overviews of the functionality/model used by the API. This is especially true if the source code of what ever you are documenting is going to be available to the developers using it (as they can always read the source code to resolve any ambiguities).

A well designed API should be intuative and difficult to use incorrectly once the main concepts of the model have been communicated. Per-method/per-class documentation doesn't really help to communicate these (model) concepts efficently, as it is so fragmented. Using the per-method/per-class approach, your users already have to be quite familiar with your API before they are even able to look in the right place for the documentation they need.

share|improve this answer

Developers in Visual Studio tend to use the /// <summary /> because apart from being able to generate an Xml usable as input for document generators, you also get tooltips during development when using the commented method/class.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.