Ruud Poutsma - 2008-01-21

The ideal way of documenting a class, method, enum, property, field (variable), project, solution  (all from now on referred to as entity) is to document both technical details _and_ funcional details. The developer unknow with the system needs to know not only about technical stuff (implementation details), but also its functional details. I'll take an example for a button. The technical description would say something like:

/// This class adds functionality for a button. It has several events like clicked and mouseover which can be used for other classes to subscribe on instances on. This class draws the button in the mthods Render and RenderPart. The Image property can be used to add an image for better visual appearance. This class inherits from Control, which adss methods Method1 and Method2. This class is not inherited from BaseButton since some very technical important reason applies.

Then, in order to understand for developers how to use it in software, the following description may apply:

/// The button is slightly different from LinkButton, in where Button draws a classical button. The LinkButton has the same functionality, but displays like a link found on a webpage. Use the button for clear UI actions, like "Save settings" or "Cancel & close". When an intensive method is called after the button is clicked (and the UI may be stuck for a little while), use the "WaitingImage" property to specify an animated GIF image. The button UI helper thread picks automatically up when UI drawing is delayed, and shows this image. Therefore, the user has feedback on the state of the system.

Technical documentation would give a description of the technical details in the entity. Like implementation, why certain technical decisions are made, etcetera. Functional documentation would focus on the use of the entity both in programmerland and in userland. Every user interaction possible with the entity is described.

This would also make it possible to be able to verify if the functional spec of the software is met in the implementation. The same is for technical spec, which also can be verified.

Almost every class has a need for both technical and functional description. It would be nice if Doxygen somehow takes this into account and has special tags for it defined. First, we need to have a discussion about the need of these tags. If this discussion outcome is positive, I would propose to implement these tags in the doxygen tag list. Then, we would need various propositions on the implementation of the tags in the forthcoming documentation generated.

For now, our code uses /// \par Technical details which does quite well. It however would be nice to have special tags defined, for better implementation. This way, when having HTML doc generated, it would be possible to click a link like "show functional details only".

To summarize: I would opt for two new tags: \technical and \functional abbreviated maybe to \tech and \func. Only recognition in preliminary versions is present, no actual implementation so we can start using it right away. When we have better worked out some nice implementation details about how to use these tags in PDF/HTML/etc implementation is possible.