United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4714350 Javadoc -quiet argument still doesn't perform as documented.
JDK-4714350 : Javadoc -quiet argument still doesn't perform as documented.

Details
Type:
Bug
Submit Date:
2002-07-12
Status:
Resolved
Updated Date:
2002-11-24
Project Name:
JDK
Resolved Date:
2002-11-24
Component:
docs
OS:
linux
Sub-Component:
doclet
CPU:
x86
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

Description

Name: nt126004			Date: 07/12/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)


FULL OPERATING SYSTEM VERSION :
n/a

A DESCRIPTION OF THE PROBLEM :
The -quiet argument is documented in the "Javadoc Options"
section (*not* the "Options Provided by the Standard Doclet"
section!) as "Shuts off non-error and non-warning messages,
leaving only the warnings and errors appear, making them
easier to view. Also suppresses the version string."

This is not the actual behavior - in particular, javadoc
-quiet (perhaps due to the standard doclet) prints:
one line per package "Loading source files for package
foo..." and one line of "Constructing Javadoc information..."

My preference would be to fix the behavior of -quiet so that
it performs as documented.  A less desireable fix would be
to amend the documentation to something like "-quiet reduces
output to warnings, errors and some progress report messages".

This makes it neccessary to parse and/or filter the output
of javadoc to extract warning and error messages in order to
tell if a doc build succeeded.

This is a resubmission of bug 4682893, since the evaluation
describing this problem is incorrect and misses the point.
Contrary to the evaluation of 4682893, the "-quiet" argument
is very clearly documented to be an argument to javadoc
itself, rather than the standard doclet (at least, in the
documentation for 1.4.0).

Either the documentation is wrong or the implementation is
wrong.  If the documentation is incorrect, then the "-quiet"
feature is of no practical value, since it is then
impossible to invoke javadoc in a way that will only emit
errors and warnings (obviously contradicting the intent of
the argument - what's the point?).

It appears that the standard doclet *also* wants to know
about -quiet, as the first paragraph in the "RUNNING
JAVADOC" section says that "The version number of the
standard doclet appears in its output stream. It can be
turned off with -quiet."

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. run "javadoc -quiet ..." on any sources which generate no
errors or warnings.

EXPECTED VERSUS ACTUAL BEHAVIOR :
Expected (note the lack of output):
% javadoc -quiet -d api -sourcepath src com.foo
%

Actual (note the output of non-error, non-warning messages):
% javadoc -quiet -d api -sourcepath src com.foo
Loading source files for package com.foo...
Constructing Javadoc information...
%

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
any source with correct javadoc comments.
---------- END SOURCE ----------

CUSTOMER WORKAROUND :
none.  Output scrapers cannot depend on -quiet to eliminate
useless and uninteresting output from javadoc.
(Review ID: 158492) 
======================================================================

                                    

Comments
EVALUATION

What documentation are you looking at?

###@###.### 2002-07-11

Indeed, the documentation in incorrect in listing this as an option of the
tool.  In fact, this is an option of the standard doclet.  See for example

http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#options

Please update the documentation to clarify this.

###@###.### 2002-07-15

While the documentation is incorrect, another request 4702454
is to change the code to conform to the documentation.
###@###.### 2002-07-25

No change to the software.  Changed only javadoc.html documentation.
Moved -quiet option to the list of standard doclet options, so it
is no longer documented as a javadoc tool option.  (Will move it
back when 4702454 is fixed)

###@###.### 2002-11-23
                                     
2002-11-23
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis

FIXED IN:
mantis

INTEGRATED IN:
mantis


                                     
2004-06-14



Hardware and Software, Engineered to Work Together