harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject Re: javadoc vs. doxygen
Date Fri, 27 Jan 2006 10:00:07 GMT
Hi Sunny,

I agree that the Java code documentation should use javadoc mark-up.
The native code is a good candidate for Doxygen-style comments, with the
advantage that if you want to generate docs that cover native and java
code (like we did for the porting guide) the Doxygen tool can cross 'the
language boundary'.

Regards,
Tim

Sunny Chan wrote:
> Hi all,
> 
> I am more of a lurker :-) but I have an opinion on this matter.
> 
> If I were to develop a java class library I would stick to Javadoc.
> Remember, things like Eclipse have support for javadoc embedded source
> code - so that when you use Eclipse's excellent content assist feature
> it will display the information about the classes/method/etc. I would be
> really annoyed if Harmony class library use Doxygen and stop Eclipse
> content assist from working
> 
> Thanks,
> Sunny
> 
> Andrey Chernyshev wrote:
>> 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 for
>> 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
> 
> 

-- 

Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.

Mime
View raw message