Mailing-List: contact harmony-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: harmony-dev@incubator.apache.org
Received-SPF: pass (asf.osuosl.org: domain of a.y.chernyshev@gmail.com
 designates 66.249.92.195 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:message-id:date:from:to:subject:mime-version:content-type:content-transfer-encoding:content-disposition;
        b=jjVMXHpjMb1glh/4aYZi5PYGb73xdEoWex0n3gsIEed75OGQBlpiy54dabeV1ddnYVL3DvbYK+cP8JltJTX0NMyXQnuhxj5rWyBFszzivIl9mojPVdXNAHaS/aoyMIWAL8SxQrx8P3Djjy9IVB0lwqPiFcrntrTjYyocUwGqMug=
Message-ID: <6928c5160601260838r649b6a3ar3f6d8f22a039bfd5@mail.gmail.com>
Date: Thu, 26 Jan 2006 19:38:17 +0300
From: Andrey Chernyshev <a.y.chernyshev@gmail.com>
To: harmony-dev@incubator.apache.org
Subject: javadoc vs. doxygen
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

There was a long discussion about writing (or non-writing) the javadoc
comments for Java class libraries. I think the another interesting
question is: what tools do we use for generating documentation for
code at Harmony?

Initial class libraries contribution suggested to use the doxygen system fo=
r
creating documentation for Java code. Security contribution then
suggested an idea of using custom tags for referencing the original
J2SE spec.

Regardless of whether custom javadoc tags idea is good or bad, I
wonder how it could be easily implemented using the doxygen. While the
doxygen may seem to be more universal approach because it covers both
C/C++ and Java code, I'm not sure if it has an internal API similar to
the doclet API supported by the javadoc tool.

For example, one can use ALIASES in doxygen configuration to define a
custom tag and then expand it to some static text. In the same
scenario, javadoc would allow to generate some more sophisticated text
depending on the current class, method or whatever other information
extracted from the Java source file where the tag was found.

Another note is that default javadoc-produced documentation and
doxygen-produced documentation have different "look-and-feel".

What people think, do we need javadoc for documenting Java sources, or
we can always live with the doxygen?
If we choose to use javadoc, whether it makes sense to develop our own
version of this tool at Harmony?


Thank you,
Andrey Chernyshev
Intel Middleware Products Division