Thread: Documenting with Doxygen

  1. #1
    (?<!re)tired Mario F.'s Avatar
    Join Date
    May 2006
    Location
    Ireland
    Posts
    8,446

    Documenting with Doxygen

    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:

    • 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)
    So the documentation can soon render my code unreadable on more sensitive areas.

    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?
    Originally Posted by brewbuck:
    Reimplementing a large system in another language to get a 25% performance boost is nonsense. It would be cheaper to just get a computer which is 25% faster.

  2. #2
    vae victus! skorman00's Avatar
    Join Date
    Nov 2003
    Posts
    594
    Personally, I think that something like Doxygen is best used for documenting functions, classes, and their intended uses and behaviors. It shouldn't have excerpts from within code blocks explaining why you chose a specific function or something around those lines.
    the code can soon become unreadable.
    I think it's very hard for too much commenting to get in the way of code readability. If you're not too attached to your coloring scheme, you can color comments to your advantage. I use the old Borland colors which had white keywords, yellow identifiers, and gray comments on a blue background. They gray comments are very easy to ignore when quickly scanning through lines of code.

  3. #3
    (?<!re)tired Mario F.'s Avatar
    Join Date
    May 2006
    Location
    Ireland
    Posts
    8,446
    True.

    I use a color scheme based on the old terminals. Green on black. With white keywords, red numbers and dark grey comments. My workmates got disgusted at seeing me programm in VB like this...

    Comments hardly get on my way. However... too much may not affect readability per se, but be distracting, which is certainly not good.

    It shouldn't have excerpts from within code blocks explaining why you chose a specific function or something around those lines.
    Actually I always found that one of the best reasons to put a comment on my comment. Although I do see your point... on the other hand, it has no place in documenting.
    Last edited by Mario F.; 07-27-2006 at 09:05 PM.
    Originally Posted by brewbuck:
    Reimplementing a large system in another language to get a 25% performance boost is nonsense. It would be cheaper to just get a computer which is 25% faster.

  4. #4
    Cat without Hat CornedBee's Avatar
    Join Date
    Apr 2003
    Posts
    8,895
    Doxygen is really, in my opinion, for API documentation, i.e. you write a library and want others to understand how to use each function. Use normal comments to explain how your code works, and use completely separate text documents (whatever form you prefer - plain, docbook, latex, html, quickbook, ...) for the high-level documentation.
    All the buzzt!
    CornedBee

    "There is not now, nor has there ever been, nor will there ever be, any programming language in which it is the least bit difficult to write bad code."
    - Flon's Law

  5. #5
    (?<!re)tired Mario F.'s Avatar
    Join Date
    May 2006
    Location
    Ireland
    Posts
    8,446
    Well, not an API, CornedBee, but I do plan to have the code distributed within 6 months after which I'm hoping to slowly create a development team.
    Originally Posted by brewbuck:
    Reimplementing a large system in another language to get a 25% performance boost is nonsense. It would be cheaper to just get a computer which is 25% faster.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Doxygen failing
    By Elysia in forum A Brief History of Cprogramming.com
    Replies: 19
    Last Post: 04-16-2008, 01:24 PM
  2. How do I make a single page doxygen doc?
    By indigo0086 in forum Tech Board
    Replies: 1
    Last Post: 01-28-2008, 09:28 AM
  3. Documenting Source Code
    By jverkoey in forum A Brief History of Cprogramming.com
    Replies: 14
    Last Post: 01-04-2008, 12:18 PM
  4. doxygen and functions
    By zxcv in forum Tech Board
    Replies: 1
    Last Post: 05-13-2006, 04:37 PM
  5. doxygen
    By Magos in forum Tech Board
    Replies: 1
    Last Post: 02-15-2006, 10:44 PM