Code Documentation - A better way?

dexter

Jul 9 2005, 03:39 PM

This is not so much a question, actually, but a bit of a plug for an interesting tool I've discovered recently.

Anyway. How does everyone else document their code? Are in-source comments sufficient? Do you write extra detailed documentation outside of the code? Or do you generate external documentation from the code?

Since I've been doing Java recently, I was in awe when I discovered javadoc. An incredible tool that allows you to generate external documentation for your code from your comments in-source.

The syntax is reasonably simple, allowing the comments to be readable in and out of the source code.

And so, I set off in search for a similar tool for C/C++. And what do I find? Doxygen. Incredible. I've already gone through and re-commented some of my reasonably completed code to include this style of commenting. Fantastic results. Instead of text documents laid out the best I can, this tool can generate all the documentation from the code in a few different styles (HTML, LaTeX, man, etc.).

Mind you, doxygen can handle:

QUOTE(doxygen.org)

C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D

Support for more languages is on the way. Also, the code has been re-worked to make it easy for developers to add support for different languages.

I seriously am never going to write external documentation for my code ever again.

And an additional question to the ones I asked above, if you do generate the code with a tool similar tool to this, what tool do you use?

I'm done plugging. Off to go re-document some more code...

osknockout

Jul 12 2005, 11:53 PM

Hello once again dexter.
In source comments should be sufficient. or you can always 'read the (expletive) manual' as Linus Torvalds used to say.

Actually there was a UNIX tool that did that did the same thing as your javadoc thingy way back, only reason I know because I look through my install packages for Linux. Of course it was just plain text, but how hard could it be to re-port it?

QUOTE

I seriously am never going to write external documentation for my code ever again.

Obviously you have never seen Freeciv code or you're crazy.

I'll find the tool someday... right now, I'm off and away.

Similar Topics

Keywords : code documentation

Simple C File Handling In Action - Small code snipet which covers most of basic file handling and navigat (3)
Yesterday I suddenly got a lot of work. The same work we try to push off, yes you are right all
formalities to get the code review incorporated and update all source code files with code review
headers. Imagine if you need to open 300 files one by one and append code review headers at the
end. Since most files are reviewed in groups of 20 to 30 files. We require one header to be placed
in say 20 to 30 files. To simplify I went back to my class assignment days and wrote this small c
utility to open all files passed on command line and open attach code review headers an...

Most Efficient Code To Get Prime Numbers - (7)

C Code, Can U Solve This? - Another interesting problem (22)

Hello, Look at the code given below CODE void fun(void) { /* Put your code here so
that main does not print 20 */ } int main() { int i = 20; fun();
printf("i = %d\n", i); return 0; } 1. You are allowed to put your code
ONLY in fun. 2. You are not allowed to change even one character in main. 3. You should not use
functions like exit(),abort() in the function fun. How do I manipulate and change the value of i?
Have fun......

A Telephone Directory Source Code In C - (2)

Well i had made this project some years before. It is a telephone directory which has a very good
User Interface operatable with scroll key. This code can be usefull in learning about file handling
and User Interface. CODE #include <stdio.h> #include <box.h> #include
<conio.h> #include <dos.h> #include <stdlib.h> #include <bios.h>
#include <graphics.h> FILE *fp; addnew2(char [],char []);
prnd(); deleteit(); info(); pl(); checkcmd();
showall(...

Source Code For Paint Like Program Under Dos In C - (2)

this is a dos program that you have been waiting for you learn from it you how to do graphic
programing under dos if you understand it your then will be able to do any kind of windows GUI in
dos it make icons and use them it deal with graphic file youwill also learn how to use mouse have
nice time ...

C++ Roman Numeral Conversion Code Help - If-else Problem (5)

thanks...

Wolfenstein Source Code Now In Public Domain - (3)

the Wolfenstein game which we enjoy it alot becouse of its highly graphic technique now u can
learn alot from it and become profissional programer becouse now its source code in Public Domain
get the source code now and make your way to become profissional programer get it at
Wolfenstein source code ...

Prob With My C Code - (4)

Hi Guys! this is a wonderful place.. although i wasnt a member till now i have referred to
these forms quite a few times for my programming solns /biggrin.gif" style="vertical-align:middle"
emoid=":D" border="0" alt="biggrin.gif" /> My problem is ::: I am writing a Code in C using
Bloodshed Dev C++ 4.9.9.2 on Windows XP. I wanted to open an executable file from my code. After
using the solution mentioned on these forums, I used QUOTE system("myprg"); It works
fine.. But the prob is that i want my C program to execute this command and then return to t...

Adding Myfileexists Function To My Basic Code? - (2)

Here is a short and basic piece of my first ever application written in Visual C++ 6.0 . I have also
commented the code well to show you EXACTLY what my code is meant to do with each function. What
exactly I am asking for, is for someone to please replace anywhere that you see "EXISTS" with the
proper function "myFileExists" to actually check to see if the file exists. Also I am asking for
anyone that may see an error in this code, to please point it out to me and how I can fix it. If
anyone can help me with getting this very basic code to work, it would be GREATLY appr...

Where Can I Get Full Souce Code Of Turbo C++ ? - where can i get full souce code of Turbo (2)

where can i get full souce code of Turbo C++ ? Al... it must be complete... complete... includes and
libraries... all.. pls.. help me.. coz i cant compile my programs.......

Looking for code, documentation

ADD REPLY / Got an Opinion!	Remove these ADs!	RAPID SEARCH!	Free Web Hosting	[X]
Express your Opinions, Thoughts or Contribute more info. to help others. Ask your Doubts & Queries to get answers, So that "Together We can help others!"	Register FREE for AD-FREE forum, Create your own topics, Ask Questions, track topics, setup subscriptions & notifications and Get a Free Website w/ Email and FTP.		500MB Space No Ads, CPanel, FTP, PHP, MySQL, EMails - 100% FREE