Javadoc: generating HTML API docs

[bruce phipps]

I am working as a technical author with some developers who have
written some Java packages.

I want to generate API docs similar to the ones distributed by Sun --
HTML format using frames. Click on the class name and the info is
displayed.

Is it possible to do all this using javadoc, or do I need some other
tools.

Links to tutorials etc. are welcome.

Bruce

 

[Phaero]

Javadoc:
http://java.sun.com/j2se/javadoc/index.jsp
Howto:
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

/Johan

 

[Hal Rosser]

Easiest way is to use something like BlueJ (BlueJ.org)

 

[bruce phipps]

Thanks Hal, looks interesting.

Easiest way is to use something like BlueJ (BlueJ.org)

 

[bruce phipps]

Thanks, Johan. I have looked at those links.
However, I would prefer a step-by-step tutorial on how to build
Sun-style API docs starting from being given the code by a programmer.
Any other good javadoc tutorials on the web?

 

[Chris Uppal]

Thanks, Johan. I have looked at those links.
However, I would prefer a step-by-step tutorial on how to build
Sun-style API docs starting from being given the code by a programmer.

Since you've said that you are working with some Java programmers, I suggest
you ask one of them to run through the basics with you.

-- chris

 

[Thomas Weidenfeller]

Thanks, Johan. I have looked at those links.
However, I would prefer a step-by-step tutorial on how to build
Sun-style API docs starting from being given the code by a programmer.

Where else should it start? You are apparently missing how JavaDoc and
similar tools (doxygen, DOC++, etc.) work:

Someone (a programmer or a tech writer) places documentation in(!) the
source code. Using a thing called an editor . In Java the standard is
that the API documentation is embedded in the source code, it is not
lying around separately. You just add a few additional HTML pages with
general descriptions if you feel like it. You feed the source code
through JavaDoc, and it generates all the nice web pages you are so keen on.

If you want to change the documentation, you drag that particular source
code out of the version control system, and edit the comments containing
the documentation. Then you run JavaDoc on the whole source code again.
When you are satisfied, you put the changed code back into the version
control system.

So you better brace yourself for having to deal with real programmers
and real source if you want to use JavaDoc documentation. Especially,
talk to them so you get the JavaDoc invocation added to the build system
instead of having to run it manually.

/Thomas

 

[Marcin Grunwald]

I am working as a technical author with some developers who have
written some Java packages.

I want to generate API docs similar to the ones distributed by Sun --
HTML format using frames. Click on the class name and the info is
displayed.

Is it possible to do all this using javadoc, or do I need some other
tools.

Links to tutorials etc. are welcome.

Bruce

Doxygen is my favourite.
Doxygen is a documentation system for C++, C, Java, Objective-C, IDL (Corba
and Microsoft flavors) and to some extent PHP, C# and D.
Usually company uses not only Java but also other languages, thanks to
Doxygen you have one type of documentation for all.

Documentation you can find here:
http://www.stack.nl/~dimitri/doxygen/manual.html

It isn't very easy to use and configure for the first time, but I think it
is worth of sacrifice.
It also draws class diagrams and has simple GUI for configuration.