harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From George Harley <george.c.har...@googlemail.com>
Subject Re: [tools] Javadoc! Javadoc! Javadoc! (the tool, not the debate...)
Date Thu, 09 Feb 2006 19:55:12 GMT
Hi Jeremy,

Whatever you feel like doing will be better than nothing.

(Sorry, I couldn't resist it)


Jeremy Huiskamp wrote:
> 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


View raw message