I'm considering using Doxygen to document my project. Have been toying with it and am quiet impressed at the features. However the code can soon become unreadable. True, not everything needs to be documented, but I'm more interested in it to document:
So the documentation can soon render my code unreadable on more sensitive areas.
- Areas of the code which need or could to be improved;
- Why I made certain choices in code;
- Explain more complex hierarchies;
- Tutor myself by providing explanations to certain areas of the code of which I have little knowledge yet.
- Explain less obvious code.
- Document my classes. (this is mostly /brief descriptions)
What do you advise?
Opening a new branch just for documenting?
Keep Doxygen out of it since, while an interesting tool, bloats the code too much?
Do everything in the trunk and limit my comments to /brief the best I can?
Just use Doxygen as a code reporting tool and do my comments in C++ fashion?