I would like to post a couple of projects as open source on google code or sourceforge they are not massive but might interest programmers that want to add or expand features i never fully developed, but what is expected by 'document your code'?
Printable View
I would like to post a couple of projects as open source on google code or sourceforge they are not massive but might interest programmers that want to add or expand features i never fully developed, but what is expected by 'document your code'?
If the projects are libraries, it would be good to use Doxygen-type of comments to document the interface and to provide usage examples of both the simplified and "real world" variety.
It means, if you have a function like this:
You should document what foo() does, and what str, num1 & num2 are (i.e. what they're used for) as well as what the return value means and any exceptions that the function might throw...Code:bool foo( std::string& str, int num1, float num2 );
Simply: Say how your project works, and how to use it
For example, most libraries are run through an API, so naturally you'd want to document what each functions does (like cpjust shows). But for like a daemon, no functions, you'd want to document all the configuration instead.
Doxygen is nice but I feel it does pollute the code with too many comments - especially in the interfaces where it is most useful. Another way to do it is record a macro in MSVS that opens a wiki page for you and you can document as you go. A guy at my workplace did this and it's actually very nice and easy to use.