Documenting Source Code

I'm in the research phase of my work report "An Analysis of Source Code Documentation Tools" and am looking to poll the waters, primarily the waters populated with those who work in proper companies.

My knowledge of the commercial lineup of source code documentation is directly proportional to the number of Google searches I do on the topic and sadly, this isn't going to cut it for me. My poll to you therefor is a rather open-ended one.

Which source code documentation software do you use in your workplace?
If you are using a commercial product, why did you choose such a product over an open-source equivalent?

Well that depends on what you mean by "documentation".

For forward documentation, I like using doxygen to extract formatted comments from source code.

For 'reverse engineering' an understanding of some existing code, I've used
- source insight http://www.sourceinsight.com/
- source navigator http://sourcenav.sourceforge.net/
- lxr http://lxr.linux.no/

I'm researching forms of forward documentation primarily. Reverse-engineering documentation doesn't apply much to the audience I'm writing my report for so I can safely ignore it, but those are interesting packages.

Doxygen is what I personally use at home and is one of the systems I'm considering in the report.

I use MS Word to document the exposed methods of functions/classes, other than that I just use inline comments of the // and /* */ type. If I had to explain what every line of code does, id never get anything done.

I use Doxygen as well, personally. It's very useful, especially when you enable cross-linked source code.

At work we use Doxygen and I'm a very big fan of it. Produces some very nice docs to go along with your code.

Yeah, at work we used Doxygen as well for our customer-facing API docs. And thanks for reminding me to write my work report, Jeff. :P

Haha, no problem. Just finished mine up last night (a great way to spend the Christmas holidays *pukes*).

Bleh, I hate writing reports, Daily progress reports, weekly reports, monthly reports, occasionaly technical analysis reports, and now a 'what you expect to accomplish in the next year' report. I suspect that the last one is really an 'explain why we should let you keep workign here' report ;)

The more interesting one is "tell us why you're leaving report".

Eh, for us it isn't that bad. Just 1500-2000 words analyzing something for the company we did a co-op term at. Luckily for me, my boss already filled out the evaluation form, so now I just need to come up with a report.

Well, my daily report is just maybe half a paragraph paraphrasing what i did that day, basically 2-3 sentences. The weekly report is really just all the daily reports copy and pasted together in one form. The monthly is the big one, usually one page detailing what was accomplished, and what still needs to be done. The assessments are what takes awhile. Anywhere from 2-100 pages depending on the subject, citing suppliers, pricing/availability, alternate techniques, existing systems, technical requirements, etc.

I work for one of those employers that 'forgets' to do evaluations unless they want to say something bad about you. Real pig **ckers, but until I get off probation, i can't move to another state where there are better jobs.

Quote:

---

Originally Posted by Salem

The more interesting one is "tell us why you're leaving report".

---

Would be funny to give them your manifesto instead.

Thanks for reminding me, I need to start writing a manifesto :D

Quote:

---

I'm leaving because of this organization can no longer provide sufficient economic oportunities for myself and my team.

---

That one will confuse the hell out of them.

or...

Quote:

---

So I can sell off my stock without being charged with insider trading.

---

Or you can just say you have an already prosperous side-career as a guild leader.