What are the most effective documentation patterns?
I've seen a great deal of various means to [or otherwise to ] comment out the code, particularly patterns on desciptions of function information and also documents objectives.
I would certainly such as to recognize what is most made use of pattern to do that [I'm particularly interested on documentation generators and also their patterns ]
Numerous tasks are making use of Doxygen, and also I assume you will not fail to select that as your selection. I've formerly been associated with a section of a much bigger task that made use of Doxygen throughout their construct procedure, do I really did not get involved in the real doc generation component of the construct, yet including the remarks was very easy and also easy.
If your task is huge with below - systems created in various languages, after that Doxygen is valuable as a result of the several languages it sustains : C+npls, C, Java, Objective - C, Python, IDL (Corba and also Microsoft tastes), Fortran, VHDL, PHP, C#, and also somewhat D.
Developers in Visual Studio often tend to make use of the
/// <summary /> due to the fact that in addition to having the ability to create an Xml useful as input for record generators, you additionally get tooltips throughout growth when making use of the commented method/class.
I made use of to place initiative right into recording code making use of these sort of automated documentation devices (doxygen, javadoc). Nonetheless, I appear to locate that the price of developing and also keeping this sort of documentation was hardly ever warranted by the gain from having it. As long as your customers can see the names/types of your function parameters.
I favor to invest the moment creating/maintaining instances and also job concentrated documentation (just how do I x?), along with basic reviews of the functionality/model made use of by the API. This is specifically real if the resource code of what ever before you are recording is mosting likely to be readily available to the programmers utilizing it (as they can constantly read the resource code to settle any kind of obscurities).
A well made API needs to be intuative and also hard to make use of inaccurately as soon as the major principles of the version have actually been connected. Per - method/per - class documentation does not actually aid to connect these (version) principles efficently, as it is so fragmented. Making use of the per - method/per - class strategy, your customers currently need to be fairly accustomed to your API prior to they are also able to search in the appropriate area for the documentation they require.