JDK-4714350 : Javadoc -quiet argument still doesn't perform as documented.
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: linux
  • CPU: x86
  • Submitted: 2002-07-12
  • Updated: 2014-05-05
  • Resolved: 2002-11-24
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
1.4.2 mantisFixed
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
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis
14-06-2004

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
23-11-2002