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 Fri, 10 Feb 2006 04:29:48 GMT
Lovely, that's exactly the kind of pointers that'll help me :)

Another thing occurred to me this evening, and that is that xdoclet  
must be extremely similar to javadoc.  I will have a poke around with  
that too and see if it isn't doable.


On 9-Feb-06, at 6:03 PM, Tim Ellison wrote:

> You may find it useful to take a look at the Eclipse Java AST APIs,
> http://help.eclipse.org/help31/index.jsp?topic=/ 
> org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/core/dom/ 
> AST.html
> http://www-128.ibm.com/developerworks/opensource/library/os-ast/? 
> ca=dgr-lnxw97ASTParser
> http://eclipsecon.org/2005/presentations/EclipseCON2005_Tutorial29.pdf
> ...
> specifically the javadoc node
> Regards,
> Tim
> 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