harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeremy Huiskamp <jhuis...@uoguelph.ca>
Subject Re: [tools] Javadoc! Javadoc! Javadoc! (the tool, not the debate...)
Date Thu, 09 Feb 2006 19:50:13 GMT
First the disclaimer: I have zero experience with writing such tools  
and precious little with compilers.  I'm just spewing what I think  
but if there are accepted ways of doing these things, it'd be great  
for anyone to step in and school me.  I'm here to learn, hopefully by  
contributing :)

What I'm thinking (and maybe this is dead obvious) is that there are  
lots of high level tasks that javac and javadoc will have in common:
-understanding and parsing the syntax of the language itself
-the relevant parts of that are anything that you can javadoc: types,  
fields, methods...
-the relation of classes in a package hierarchy, like when a method  
takes an @arg of type java.lang.String, you've got to resolve that  
and produce a link to the String javadoc
-essentially having the ability to take a target dir and produce a  
walkable data structure of all it's contents

Of course, it's not a perfect match.  Javadoc needs to treat javadoc  
comments as different from other comments (not toss them) and it  
doesn't need to understand things at a level finer than, say, methods  
(doesn't need to know about if statements, loops, etc).  But there's  
enough there that the javadoc front end could essentially be the  
javac frontend with the addition of handling the actual javadoc  
contents.  Then, of course, the back end of the compiler spits  
out .class files while javadoc spits out html or whatever other  
format you need, but that's the reason for the separation between  
front and back ends :)

What I could do is take the eclipse compiler and see what parts of it  
can be reused.  I don't know anything about it so I won't offer any  
speculation now.  Also, obviously eclipse has it's own javadoc  
functionality.  Is that something that can be borrowed?

Assuming the easy case, that the tools are all there for poaching  
with minimal work, what would the proper action be?  It could be  
stated that harmony will use the eclipse tools and you should go get  
them from eclipse if you want them (at least for the time being,  
until harmony gets to the point of being packaged up as a useable  
jdk).  I gather that's the current status of the compiler.  Or  
harmony could host the currently accepted binaries.  Or the source  
code could be taken into svn, in which case there's the question of  
keeping in sync with the original tool.  In all likelihood, it won't  
be that simple and harmony will have some of it's own modifications...

Having asked so many questions, I'm now expecting to be told that  
whatever I feel like doing will be better than nothing :-p  I'm off  
to see what I can find out about the eclipse toolset.

Jeremy

On 9-Feb-06, at 1:41 PM, Geir Magnusson Jr wrote:

>
>
> Jeremy Huiskamp wrote:
>> What would be the suggested route for coming up with a javadoc tool?
>
> Open up an editor, and start typing! :)
>
>   Is
>> there something out there now that could be imported and shaped  
>> up?  At the other extreme, I'm envisioning busting out jflex/cup  
>> and doing a from-scratch implementation.  I'm thinking there would  
>> be a lot of overlapping functionality with the front end of a  
>> compiler so should the two tools be considered together?  Harmony  
>> doesn't have a start on it's own compiler yet, correct?
>
> We were planning to just use the eclipse compiler.  No reason to  
> rewrite.
>
> I guess the best thing to do is do a quick write-up on how you  
> might go about this.  Someone here must have some ideas to share  
> too...
>
> geir
>
>> Jeremy
>> On 31-Jan-06, at 2:14 PM, Geir Magnusson Jr wrote:
>>> Ok - this isn't about the finer points of confusion surrounding  
>>> documentation....
>>>
>>> We need a javadoc tool for Harmony.
>>>
>>> The current conversation is a diversion from this, which I recall  
>>> was the original motivation behind the current generation of this  
>>> discussion.
>>>
>>> So, anyone interested?  We need all the tooling actually...
>>>
>>> geir


Mime
View raw message