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: [tools] Javadoc! Javadoc! Javadoc! (the tool, not the debate...)
Date Thu, 09 Feb 2006 23:03:08 GMT
You may find it useful to take a look at the Eclipse Java AST APIs,


specifically the javadoc node


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


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

View raw message