API doc: missing bits

[Ed Staub <es...@silknet.com>]

The distributed API doc doesn't include org.apache.xerces.framework.
There may be a good reason for this, but the effect is that some important
methods on more public packages are not documented.  

For instance, there's no mention in the javadoc of the parse() method on
org.apache.xerces.parsers.DOMParser.

(If there's a better venue for reporting this kind of stuff, please clue me
in.)

Thanks,
-Ed Staub
Kana Communications, Inc.

Re: API doc: missing bits

[Theofanis Vassiliou-Gioles <va...@fokus.gmd.de>]

Hi Ed,

I experienced the same problem. In my opinion 
at least the framework-package should be included. 
Therefore I changed PACKAGES in src/Makefile.inc to include
org.apache.xerces.framework.

Just include this package an rebuild the api. 
Hope this helps you.

Here an idea how to overcome this problem in the future.
I think the main problem in building api-docs in this way is, that you
have to name each package that should be included in the build.
But I think this should be the default behaviour.

So why not building the PACKAGE variable for example in the following way:
PACKAGES = `find ./ -type d -print | egrep -v -f exclude |  sed -e 's/\//./g' | sed -e 's/\.\.//g'`

The file "exclude" contains all packages that should not be in the
api-doc. So packages can not be "forgotten" in the api-doc. 
If however, there is a good reason to exclude packages just put
them into the "exclude" file. A good idea would also be then to document
the "good reason" to exclude the packages.

Best regards,

Theo
__________________________
Theofanis Vassiliou-Gioles      email: vassiliou@fokus.gmd.de
GMD FOKUS                       phone: +49 (30) 3463 - 7346
Kaiserin-Augusta-Allee 31       room : 3008
D-10589 Berlin                  http://www.fokus.gmd.de/usr/vassiliou/

On Fri, 26 May 2000, Ed Staub wrote:

> The distributed API doc doesn't include org.apache.xerces.framework.
> There may be a good reason for this, but the effect is that some important
> methods on more public packages are not documented.  
> 
> For instance, there's no mention in the javadoc of the parse() method on
> org.apache.xerces.parsers.DOMParser.
> 
> (If there's a better venue for reporting this kind of stuff, please clue me
> in.)
> 
> Thanks,
> -Ed Staub
> Kana Communications, Inc.
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
> 
>