United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4634891 sdtddoclet: Override of private method shouldn't be doc'd - createBufferStrategy
JDK-4634891 : sdtddoclet: Override of private method shouldn't be doc'd - createBufferStrategy

Details
Type:
Bug
Submit Date:
2002-02-07
Status:
Resolved
Updated Date:
2003-04-12
Project Name:
JDK
Resolved Date:
2002-09-02
Component:
docs
OS:
other,generic
Sub-Component:
doclet
CPU:
generic
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports
Duplicate:

Sub Tasks

Description

Name: rmT116609			Date: 02/07/2002


DESCRIPTION OF THE PROBLEM :

Class: java.awt.Window
Method: createBufferStrategy (both signatures)

http://java.sun.com/j2se/1.4/docs/api/java/awt/Window.html#createBufferStrategy(int)

http://java.sun.com/j2se/1.4/docs/api/java/awt/Window.html#createBufferStrategy(int, java.awt.BufferCapabilities)


All info is correct except:


Overrides:
    <a>createBufferStrategy</a> in class Component

Where <a> represents a broken link to the createBufferStrategy method.
The "createBufferStrategy" in Component is private.
So either the link should not appear, or the override statement should not
appear.

(Review ID: 139392) 
======================================================================

                                    

Comments
EVALUATION

Yes, this is true.  Apparently someone found a new javadoc bug.  I wondered if
Component.createBufferStrategy was supposed to be public, but engineering (Mike
Martak) said no, it's supposed to be private.  Doug Kramer said we haven't 
received a bug like this before, and he found another instance of it.  Here is 
his email:

I also notice that Component.setIgnoreRepaint has the same broken link
to createBufferStrategy:

See Also:
            getIgnoreRepaint(), #createBufferStrategy, BufferStrategy,
            GraphicsDevice.setFullScreenWindow(java.awt.Window)


I am changing the category of this bug and reassigning to Doug.

###@###.### 2002-03-19

I modified the description slightly.  Unclear to me if we should 
just remove the broken link or remove the entire Overrides statement.
Changed synopsis from:
  A missing link in doc for java.awt.Window.createBufferStrategy()
to:
  sdtddoclet: Override of private method shouldn't be doc'd - createBufferStrategy
###@###.### 2002-03-19

Josh concurs with the solution for Javadoc to not generate the override statement (neither the text nor link), as it is not an override.  
Technically speaking, private methods cannot be overridden, because 
they cannot be accessed outside their class.  In addition, references
to private methods should not appear in a public API.
###@###.### 2002-04-17

The bug submitter claims that the doclet generates incorrect
documentation about overriden private methods.  My regression tests
(included in webrev) show that this is not true.  However, the doclet
does include documentation about overriden "package private" methods,
which is a bug if the package private method is not included in the
documentation.  We should only link to overriden package private methods
when -package or -private is used.

When a package private MethodDoc is returned by
MethodDoc.overridenMethod(), I notice that isIncluded() returns true for
that package private method, even though the method is not included in
the documentation.  I think this is a bug.  I have fixed the
isIncluded() method in the JavaDoc tool.  By fixing the isIncluded()
method, the doclet is able to detect when the overriden method is not
documented and avoid printing a bad link.
###@###.### 2002-06-01

This bug has been fixed in the Javadoc tool and the standard doclet. 
###@###.### 2002-07-15
                                     
2002-06-01
PUBLIC COMMENTS

This bug has been fixed.  We no longer link to package private overriden methods unless they are visible in the documentation (i.e.  when -package or -private is used).
###@###.### 2002-06-01
                                     
2002-06-01
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis
mantis-b02

FIXED IN:
mantis
mantis-b02

INTEGRATED IN:
mantis
mantis-b02


                                     
2004-06-14



Hardware and Software, Engineered to Work Together