Skip site navigation (1)Skip section navigation (2) 
Date:      Wed, 7 Mar 2001 19:09:46 +0100
From:      Ernst de Haan <ernst@jollem.com>
To:        Nate Williams <nate@yogotech.com>
Cc:        FreeBSD Java mailing list <freebsd-java@FreeBSD.ORG>
Subject:   Re: JDK install: Unpack source ?
Message-ID:  <20010307190946.A1272@c187104187.telekabel.chello.nl>
In-Reply-To: <15014.30024.816436.328056@nomad.yogotech.com>; from nate@yogotech.com on Wed, Mar 07, 2001 at 10:52:08AM -0700
References:  <20010307113713.A2897@c187104187.telekabel.chello.nl> <15014.29052.149045.46268@nomad.yogotech.com> <20010307184758.A1163@c187104187.telekabel.chello.nl> <15014.30024.816436.328056@nomad.yogotech.com>
next in thread | previous in thread | raw e-mail | index | archive | help 
Hi Nate,

> Why do you need to run javadoc?  The documentation is provided complete
> in another port, so you should never need to run javadoc on the base
> stuff, AFAIK.

We have a miscommunication. I am a Java software developer, I create Javadoc
API documentation myself. This is what I run javadoc for. We use Ant to
generate the Javadoc documentation during the build process. This is what the
concerning target in the build file looks like:

   <target name="javadoc" depends="prepare">
      <javadoc
         sourcepath="${javadoc.src.path}"
         destdir="${javadoc.dir}"
         packagenames="${packages}"
         version="yes"
         use="yes"
         author="yes"
         private="no"
         windowtitle="${javadoc.title}"
         doctitle="${javadoc.title}"
         bottom="${javadoc.footer}"
      >
         <link
            offline="true"
            href="http://java.sun.com/products/jdk/1.2/docs/api/"
            packagelistLoc="${jdk.javadoc.location}"
         />
         <link href="file://${horizon-common.home}/doc/api/" />
         <link href="file://${horizon-expr.home}/doc/api/" />
      </javadoc>
   </target>

And up in the "init" section:

      <!-- Javadoc options -->
      <property name="javadoc.title"    value="${title} ${version}" />
      <property name="javadoc.footer"   value="&lt;SMALL&gt;&lt;EM&gt;Copyright &#169; 2000 &lt;A href=&quot;http://www.eventsys.com/&quot;&gt;Event-Driven Systems BVBA, Belgium&lt;/A&gt;, All Rights Reserved.&lt;/EM&gt;&lt;/SMALL&gt;" />
      <property name="javadoc.src.path" value="${src.java.dir}:${horizon-common.src.dir}:${horizon-expr.src.dir}" />
      <property name="packages"         value="com.eventsys.horizon.worldmodel,com.eventsys.horizon.worldmodel.browser,com.eventsys.horizon.worldmodel.parsers" />

Seems I don't include the JDK source code at the moment. But I do recall that
I wanted to include it. Notice that I do include the source code for some
other libraries.

> > But while I'm writing this I'm wondering if (a) javadoc supports .jar
> > files in the source path and (b) if I *really* need the source code
> > for API docs generation, the Javadoc API docs should be enough.
> 
> Now you're talking . :)

No I mean for the generation of my API docs. You misunderstood me, I think =)

> > And the times I need to check the source code, is usually because the
> > API docs don't tell me half the story, or because I want to know what
> > approach is used in the JDK, for example w.r.t. the implementation of
> > some collection classes.
> 
> Having done that for JDK1.0 and JDK1.1, I recommend you avoiding the
> sources if at all possible.  Sun *radically* changed the internals class
> implementations from 1.0 -> 1.1 -> 1.2 -> 1.3.  By looking at the
> internals, you are more likely to depend on 'internal' behavior that
> will no longer be relevant in subsuquent releases.

Okay, I agree, but (a) for some AWT or Swing stuff there's hardly any choice
but to check the source code if you want to get certain things done, and (b)
when looking at the implementation of the collection classes, I don't use that
information to assume a certain implementation, but just so that I can be sure
that my implementation is 'better' (at least in the context of our project).

> Again, sometimes you have very little choice, but too many times this
> comes back to bite you. :(

Yeah I know :) I've worked with JDK 1.0.2 too, and I *really* had to check the
source code every now and then, because I couldn't get all information from
the Javadoc comments. Good old days. Not. ;)

--
Ernst

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-java" in the body of the message

Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010307190946.A1272>