[PROPOSAL] javadoc refactoring and supporting gjdoc

[Takashi Okamoto <to...@kun.ne.jp>]

Hi ant,

Current javadoc task support only SUN's javadoc. However there are
another javadoc engine like gjdoc which is GNU's javadoc altenative. 

If ant supports gjdoc, it would be helpful for diffusion of gjdoc.
In the past, I refactored rmic for other than SUN's rmic
implementation. This is second tackle for it. 

(1)In the first, I'll refactor JavadocTask class with Adaptor and
   Factory Pattern like rmic. So, current JavadocTask class will be
   splitted into

  org.apache.tools.ant.taskdefs.JavadocTask.java
  org.apache.tools.ant.taskdefs.javadoc.JavadocAdapter.java
  org.apache.tools.ant.taskdefs.javadoc.JavadocAdapterFactory.java
  org.apache.tools.ant.taskdefs.javadoc.SunJavadoc1.java
  org.apache.tools.ant.taskdefs.javadoc.SunJavadoc4.java

SunJavadoc1 and SunJavadoc4 is same as javadoc1 and javadoc4 in
current Javadoc implementation though I don't know why such named. In
addition to this, I may extract inner class at JavadocTask class
because it have too many inner class and I don't feel it's good.

(2)Second, I'll write gjdoc Adaptor for JavadocTask.

I would like ask you, is it good and my patch is acceptable or not.

This modification is useful for gcj ,kaffe and other opensource javavm
which couldn't bundled SUN's javadoc.

regards,

Takashi Okamoto

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org

Re: [PROPOSAL] javadoc refactoring and supporting gjdoc

[Stefan Bodewig <bo...@apache.org>]

On Sat, 27 Sep 2003, Takashi Okamoto <to...@kun.ne.jp> wrote:

> Debian have 'main' and 'contrib' section. 'main' group is official
> debian package which mean it's compiled and run opensource
> platform(e.g. kaffe/gcj) 'contrib' group is non-official which mean
> it's opensource but can't be built nor run with opensource platform.

I'll refrain from commenting on this policy.

> So, most of opensource java software create javadoc document with
> javadoc task. This means I can't put such a package into main
> section beacuse javadoc depend on SUN's implentation which is not
> oss.

Strictly speaking, you can build the package but you can't build the
docs.

> Then ,if gjdoc task is separated, I must modify build.xml file for
> all javadoc generation to create Debian package.

The alternative - coming in an Ant 1.6 release close to you soon - is
to provide a different build file for your Debian build.  In that
build file <import> the original build file and override the target[1]
that creates the javadocs with one that uses <gjdoc>.

> BTW, I already send the patch in bugzilla. Please close it.

will do.

Stefan

Footnotes: 

[1] I've never thought I'd recommend to override targets - and
certainly not that soon.  Let's say I haven't been in control of
myself while I've written the paragraph above.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org

Re: [PROPOSAL] javadoc refactoring and supporting gjdoc

[Takashi Okamoto <to...@kun.ne.jp>]

Hi Stefan,

From: Stefan Bodewig <bo...@apache.org>
Subject: Re: [PROPOSAL] javadoc refactoring and supporting gjdoc
Date: 26 Sep 2003 11:40:12 +0200
> > In the past, I refactored rmic for other than SUN's rmic
> > implementation.
> 
> Yes, I remember that.  

I remeber you take some of my patches too, thanks. 

> But <rmic> is a lot easier to find a common interface for, I'm
> afraid.  How many of javadocs attributes or nested elements would be
> supported by gjdoc?  50%, 80% or all?

In gjdoc case, less than 50%. You are right, I should write <gjdoc>
task independent. But main problem remains.

This is not ant problem but I would like to explain why I propose
supporting gjdoc. If I hear good idea to resolve this problem, I'm
happy. 

I maint java oss packages for Debian. Debian have 'main' and 'contrib'
section. 'main' group is official debian package which mean it's
compiled and run opensource platform(e.g. kaffe/gcj) 'contrib' group
is non-official which mean it's opensource but can't be built nor run
with opensource platform.

So, most of opensource java software create javadoc document with
javadoc task. This means I can't put such a package into main
section beacuse javadoc depend on SUN's implentation which is not
oss. I would like to increase official package for Debian. Most of
javadoc task in build file seems not to use special option. If it use,
I can igonore to obtain javadoc in most case. Then ,if gjdoc task
is separated, I must modify build.xml file for all javadoc generation
to create Debian package. I won't like to modify build.xml for each
package and I propose JavadocAdapter.

> javadoc1 and javadoc4 are flags.  There are certain attributes that
> can not be used for the javadoc version of JDK 1.1 as they've been
> added later.  Likewise the javadoc for JDK 1.4 added new stuff.
> 
> You'd rather need SunJavadoc1.1, SunJavadoc1.2 and SunJavadoc1.4 where
> SunJavadoc1.1 would only use the attributes and nested elements that
> now get used if javadoc1 is true.  SunJavadoc1.2 all that will be used
> if both flags are false and SunJavadoc1.4 all those where javadoc4 is
> true.
 
I see. If I refactor it, Sun's implementation should be splited into
each Javadoc.

Ok. Currently, I suspend supporting gjdoc. But when gjdoc grown up or
I found other javadoc compatible tool, I'll try again.

BTW, I already send the patch in bugzilla. 

http://nagoya.apache.org/bugzilla/show_bug.cgi?id=23441u

Please close it.

thanks,

Takashi Okamoto

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org

Re: [PROPOSAL] javadoc refactoring and supporting gjdoc

[Stefan Bodewig <bo...@apache.org>]

Sorry, I meant to respond to this a lot earlier.

On Fri, 12 Sep 2003, Takashi Okamoto <to...@kun.ne.jp> wrote:

> Current javadoc task support only SUN's javadoc. However there are
> another javadoc engine like gjdoc which is GNU's javadoc altenative.

How similar/different are javadoc and gjdoc?  Does gjdoc support
something like doclets?

If they are too different, I'd rather suggest a completely new task
than merge two things that don't really lend themselves to merging.

> If ant supports gjdoc, it would be helpful for diffusion of gjdoc.

This is not really a concern for Ant, sorry.  I'd even go so far to
say that the "natural home" for a <gjdoc> task would be gjdoc and not
Ant.

> In the past, I refactored rmic for other than SUN's rmic
> implementation.

Yes, I remember that.  But <rmic> is a lot easier to find a common
interface for, I'm afraid.  How many of javadocs attributes or nested
elements would be supported by gjdoc?  50%, 80% or all?

> SunJavadoc1 and SunJavadoc4 is same as javadoc1 and javadoc4 in
> current Javadoc implementation though I don't know why such
> named.

javadoc1 and javadoc4 are flags.  There are certain attributes that
can not be used for the javadoc version of JDK 1.1 as they've been
added later.  Likewise the javadoc for JDK 1.4 added new stuff.

You'd rather need SunJavadoc1.1, SunJavadoc1.2 and SunJavadoc1.4 where
SunJavadoc1.1 would only use the attributes and nested elements that
now get used if javadoc1 is true.  SunJavadoc1.2 all that will be used
if both flags are false and SunJavadoc1.4 all those where javadoc4 is
true.

Stefan

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org