I’ve always thought Javadoc was one of the best features of Java. The Javadoc pages for the core API are invaluable for finding what I need very quickly. The utility can be run on any Java source files to generate a nice set of HTML pages that gives you a thousand-foot view of packages, classes, members, and method signatures. Nothing special or extra is required. Of course, you’ll often want to add comments and descriptions and that’s done by following commenting conventions that Javadoc can recognize and insert automatically into its HTML output, but you don’t need to do this for Javadoc to work.
Python’s docstring conventions are not quite as elegant, in my opinion, but they work just as well. Documentation is so much more important in a dynamic language like Python because unlike Javadoc, the pydoc utility can’t determine types. So if a parameter for a function or object method is “user,” one needs to know whether to pass in a User object, a username string, an integer id… or whether any of those will work.
Both Python’s docstring and Javadoc let you document as-you-go, eliminating or reducing the need for documentation as a separate task. If you change something, the documentation is right there for you to update.
Perl’s POD format isn’t nearly as convenient. The markup is oriented more towards layout and formatting rather than following the structure of the code. You can write section headers, indent, and list items in the documentation, but you don’t really attach them to subroutines or methods. Well, you can, sort of, with “=item” but each item must be nested inside other markup, and it feels kludgey and weird. The consequence is that the documentation feels really much separate from the code, even if it resides in the same file. It doesn’t encourage documentation as you go.
In the perl project I worked on, I wrote some POD comments in the very beginning but it fell by the wayside. I should have kept up with it, but it felt like an extra thing to do. My client’s taken over the code, and he’s spending time reading a lot of code to figure out what the parameters should be for various calls. In a dynamic language, there’s no easy way around this if there’s no documentation. Plus perl’s subroutine syntax can make it very difficult to decipher parameter lists quickly. It’s frustrating. I can’t really blame Perl for my own failure to write extensive documentation, but I must say, the idiosyncrasies of POD don’t exactly make it easy.