Improving the public api javadoc

[Daniel John Debrunner <dj...@apache.org>]

Along the lines of improving getting started I was looking at Derby's
public api javadoc, available at:

http://db.apache.org/derby/javadoc/publishedapi/

This is another case where the information is there, but the reader is
not given any guidance about what to look for once they get to that page.

I added an overview page (published_api_overview.html) that's picked up
by the overview option of Javadoc. The information is an expanded
version of the README file. I actually started trying to add an overview
to the internals javadoc, but that target doesn't build for me.

I also added a package.html for org.apache.derby.jdbc, to give an
overview of the JDBC drivers and data source classes.

You can see these changes by building the publishedapi ant target from
the top-level directory. At some point the link above will be refreshed
to pick up the changes. I don't know how/when that is generated,
currently it's about 5 days old.

Feel free to make improvements to this pages or add other package.html
files for the packages with public api classes.

Dan.

Re: Improving the public api javadoc

[Andrew McIntyre <mc...@gmail.com>]

On Feb 12, 2006, at 5:27 PM, Daniel John Debrunner wrote:

> I see this error:
>
>   [javadoc] Loading source file
> C:\_work\svn_clean3\trunk\java\tools\org\apache\
> derby\tools\sysinfo.java...
>   [javadoc] 1 error

I think this is javadoc re-reporting an error that occurred earlier  
while loading the source files. This could happen if there were files  
that were inadvertently selected by an Ant fileset and then passed to  
javadoc. If you capture the full output of the build target and then  
search for 'error' you should find the culprit. For example, if you  
patched a file and there were rejected parts of the patch,  
{somefile}.java.rej might be selected by Ant for the fileset, and  
then later rejected by javadoc. We can fix this by excluding the  
offending pattern from the filesets in the derbydocs_exclusions.ant  
file in tools/javadoc.

>> The nightly sync will  resume again tonight.
>
> Hmmm, I see new content, but it's from Fri Feb 10th?

For uninteresting reasons, what I sync'd over yesterday had been  
built on Friday. A fresh batch of javadoc built from the latest  
source was sync'd over a few minutes ago. This latest batch does not  
include the J2ME or JDBC 4.0 classes, but they should appear tomorrow.

andrew

Re: Improving the public api javadoc

[Kev Jackson <ke...@it.fts-vn.com>]

>I see this error:
>
>  [javadoc] Loading source file
>C:\_work\svn_clean3\trunk\java\tools\org\apache\
>derby\tools\ij.java...
>  [javadoc] Loading source file
>C:\_work\svn_clean3\trunk\java\tools\org\apache\
>derby\tools\sysinfo.java...
>  [javadoc] 1 error
>
>
>Executing ant -verbose didn't expand any on the not very helpful
>
>[javadoc] 1 error
>
>:-(
>
>  
>
Try ant -debug - I'll take a look at the javadoc task and see if there 
is a problem with verbose messages being recorded correctly

Kev

Re: Improving the public api javadoc

[Daniel John Debrunner <dj...@apache.org>]

Andrew McIntyre wrote:

> 
> On Feb 12, 2006, at 12:51 PM, Daniel John Debrunner wrote:
> 
>> I actually started trying to add an overview
>> to the internals javadoc, but that target doesn't build for me.
> 
> 
> Is there a problem with the build target? It is currently working for  me.

I see this error:

  [javadoc] Loading source file
C:\_work\svn_clean3\trunk\java\tools\org\apache\
derby\tools\ij.java...
  [javadoc] Loading source file
C:\_work\svn_clean3\trunk\java\tools\org\apache\
derby\tools\sysinfo.java...
  [javadoc] 1 error


Executing ant -verbose didn't expand any on the not very helpful

[javadoc] 1 error

:-(

>> You can see these changes by building the publishedapi ant target from
>> the top-level directory. At some point the link above will be  refreshed
>> to pick up the changes. I don't know how/when that is generated,
>> currently it's about 5 days old.
> 
> 
> I'm glad you noticed this, I needed to tweak the sync of the javadoc 
> after the changes I made last week. I just sync'd a fresh copy, but I 
> had to Shift-Reload to see the new files. The nightly sync will  resume
> again tonight.

Hmmm, I see new content, but it's from Fri Feb 10th?

Dan.

Re: Improving the public api javadoc

[Andrew McIntyre <mc...@gmail.com>]

On Feb 12, 2006, at 12:51 PM, Daniel John Debrunner wrote:

> I actually started trying to add an overview
> to the internals javadoc, but that target doesn't build for me.

Is there a problem with the build target? It is currently working for  
me.

> You can see these changes by building the publishedapi ant target from
> the top-level directory. At some point the link above will be  
> refreshed
> to pick up the changes. I don't know how/when that is generated,
> currently it's about 5 days old.

I'm glad you noticed this, I needed to tweak the sync of the javadoc  
after the changes I made last week. I just sync'd a fresh copy, but I  
had to Shift-Reload to see the new files. The nightly sync will  
resume again tonight.

andrew