Generating API Documentation? 54
Preda asks: "I have been recently tasked with generating API documentation for new and legacy code. Given the amount of legacy code (in C, VB6, VB.NET, PHP, and other languages) and new code that needs to be documented, are there any easy auto generating API programs out there. I have done a few searches but nothing that I have found stood out as a 'use me' solution. Does anyone have any advice?"
doxygen, commentator (Score:5, Informative)
Other than that, there's the Commentator [cenqua.com]...
Re:doxygen, commentator (Score:1)
Doxygen is good (Score:4, Informative)
* This is a function that does something.
*
* @param foo first argument
* @param bar second argument
*
* @return some useful value
*/
The comments have minimal markup, inside the code source, so when you edit the actual functions you can also read (and update) the comments.
Re:doxygen, commentator (Score:2)
Wiki? (Score:4, Insightful)
Why not cut down on the workload for you by setting up a documentation wiki and asking the development team to help?
Re:Wiki? (Score:2, Interesting)
Standardized output (Score:4, Informative)
Don't auto generate (Score:5, Insightful)
Re:Don't auto generate (Score:2)
Is it too hard to put a javadoc tag in the comment, or a maybe even a pod tag?
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:5, Insightful)
Re:Don't auto generate (Score:3, Insightful)
Plus any developer worth his salt comments when he has to work with other programmers.
I used to think so, but now I'm doing full unit testing, refactoring, and pair programming. I now think comments are the second-worst place for information about the code, (followed only by external documentation).
The best choice is to write code that's clear: short methods, clear variable names, extrac
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:4, Interesting)
Like art, most programmers know good code when they see it. Only some programmers can easily describe why the code is good in terms like the above. Even fewer have an instinct for creating beautiful code.
If you are fortunate enough to work on a small, hand-picked team of talented programmers, I envy you. Most departments tend to spread the talent around to give the most overall benefit. In order for a team to be effective, the least talented programmer on the team needs to be able to maintain code written by the most talented, and vice-versa. The coding standards should reflect that. A truly great programmer always keeps the skill level of his or her current and future colleagues in mind.
Re:Don't auto generate (Score:2)
Which is part of wy I'm so big on pair programming. Few people are good enough to articulate why the length of a method is right, but if you're continously pairing with
Re:Don't auto generate (Score:2)
Readability. If it can't be read easily, then it is too short
"How long is too long?"
the moment is does more then one task.
"What is the difference between a clear name and an unclear one? "
I should be able to read a variable and know why it is there.
Coding is not art, it is engineering.
Good in engineering can have beauty, but that is not the same as art.
Art is created for the art. To create code with the idea that you are creating art is folly, and subject to 'mood coding'
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:1)
Unit tests should also tell you how code is supposed to work. Perhaps you need clearer unit tests. Think of them as executable documentation.
If the internal workings are so complicated t
Re:Don't auto generate (Score:2)
Internal workings *always* need explaining. Maybe not to you, but to the next guy to work on the code. Not leaving that explanatio
Re:Don't auto generate (Score:1)
It sounds to me like you've never encountered very good unit tests. Try doing test-driven development [agiledata.org] for a couple of months and you may
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:1)
Really, until you try TDD, you'll never get how unit tests can accomplish the things I'm talkin
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:2)
This, is why you are incorrect.
http://online.wsj.com/article/0,,SB11274368032834
Philosophies such as yours don't scale. Period.
Re:Don't auto generate (Score:2)
No, they won't. I know people who work at MS- from talking to them the problems are far deeper. It has to do with a very old, poorly designed code base that just had layers of cruft added on. Its a problem at a different level than what we're discussing.
Tools don't make up for good solid design. Nothing does. Th
Re:Don't auto generate (Score:2)
Re:Don't auto generate (Score:2)
I disagree. The farther away the documentation is from the source code, the less likely it is to get written or updated. The best-maintained documentation is inline, like Javadocs, Python docstrings, pod, or doxygen comments. When you make a change to the source, the documentation you're invalidating is right there. It takes almost deliberate blindness to not keep it in sync.
Second best is a wiki. I
NaturalDoc (Score:2, Informative)
Natural Docs [naturaldocs.org] can solve problem of weird formats. It is rather straitforward, looks nice in code and very easy to use. Besides, it allows you to write docs in separate files if developers really give up commenting in code. As for me, this is the best doc autogenerator I've ever seen.
Re:Don't auto generate (Score:2)
Ya! (Score:2)
nDoc for all things .net (Score:4, Interesting)
Its nice since the
-Rick
Do you really want to suceed at this? (Score:3, Funny)
This is usually what a company asks an important developer to do before they let him/her go. I hope this isn't your situation though. Hopefully they are promoting you to manager and letting you hire/train new employees (using your documented code).
Re:Do you really want to suceed at this? (Score:2)
-Rick
Re:Do you really want to suceed at this? (Score:1)
My preferred methodology for documentation is to write very legible code using consistent naming conventions and coding patterns followed by a complete code
Re:Do you really want to suceed at this? (Score:2)
You deserve a better company than that. If that is your company's style, then a move to another company is the best thing that could happen to you.
Commentator (Score:5, Funny)
Re:Commentator (Score:1)
bitterness=9,profanity on
int sum = 0;
//don't even fucking *think* about asking
for (int i= 0; i < a.length; i++) {
sum += a[i];
}
Generating API Documentation? (Score:1)
Web, Weave and Tangle (Score:5, Insightful)
Instead of writing code and not commenting it, you write a book on what you want your code to do, littered with examples of how it works and justifying why, and the tools somehow produces the C files and compile the library for you.
At least its something like that, the weave documentation didn't seem clear enough at the time for me to get it to do anything useful. *cough* I needed instructions not why's and because's
However it looks like folk are doing something useful with it: http://www.ox.compsoc.net/~gemini/simons/webperl/ [compsoc.net]
Doxygen, gtk-doc, vbdox, ... (Score:4, Informative)
Doxygen [stack.nl] is a good tool for many languages. It works best for C++, but it also has some limited support for PHP, which is in your list of requirements. There is also a fork of Doxygen called DoxyS [doxys.dk]. It generates prettier output for C++ but may not support the other languages as well as Doxygen. Another tool inspired by Javadoc [sun.com] is PHPDoc [phpdoc.de] for PHP code. However, it does not seem to be actively developed anymore.
For plain C code, I prefer gtk-doc [gtk.org], which generates better output than Doxygen (IMHO, and for C only). You can see an example of the gtk-doc output by browsing the GTK+ API documentation [gnome.org].
Since you also mention Visual Basic, you could have a look at VBDOX [sourceforge.net]. I haven't tried it myself so I don't know if it works well. There are some screenshots on their site, so maybe you should have a look and decide if you like the results.
Robodoc (Score:1)
http://www.xs4all.nl/~rfsber/Robo/robodoc.html [xs4all.nl]
D OXYGEN (Score:1)
Doxygen is not an answer yet (Score:2, Interesting)
Use Doxygen (Score:2)
Re:Yes. (Score:2)
Doc-O-Matic (Score:1)