db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Knut Anders Hatlen (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DERBY-6552) The public api includes methods inherited from superclasses which aren't in the public api and so have no javadoc comments
Date Tue, 17 Jun 2014 07:50:01 GMT

    [ https://issues.apache.org/jira/browse/DERBY-6552?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14033528#comment-14033528
] 

Knut Anders Hatlen commented on DERBY-6552:
-------------------------------------------

Thanks for making these changes, Dag.

One question:

{quote}
I removed some Javadoc from non-public members in the API classes, and replaced them with
end-of-line comments instead (to avoid user confusion).
{quote}

Could this be solved by changing the publishedapi build target so that it only includes public
methods in the generated javadoc instead? It looks like it currently calls the javadoc task
without specifying access level, which means it'll include both public and protected members.
If the problem was that some protected methods were included in the generated javadoc, it
should be possible to avoid that by adding access="public" to the invocation of the javadoc
task. (Advantages of preserving the comments as javadoc: They'll still show up in the more
detailed engine javadoc, and IDEs will be able to give a useful description of methods/fields
without actually navigating to them.)

> The public api includes methods inherited from superclasses which aren't in the public
api and so have no javadoc comments
> --------------------------------------------------------------------------------------------------------------------------
>
>                 Key: DERBY-6552
>                 URL: https://issues.apache.org/jira/browse/DERBY-6552
>             Project: Derby
>          Issue Type: Bug
>          Components: Javadoc, JDBC
>    Affects Versions: 10.11.0.0
>            Reporter: Rick Hillegas
>            Assignee: Dag H. Wanvik
>         Attachments: derby-6552-exp.diff, derby-6552-exp.status, derby-6552-link-fixes.diff,
derby-6552-restructure-even-more.diff, derby-6552-restructure-more.diff
>
>
> We simplified and cleaned up the public api in 10.11. Now, however, we've lost the javadoc
for methods which customers may need to use. For instance, ClientDataSource contains a method
called setSsl() which is inherited from ClientBaseDataSourceRoot. But since ClientBaseDataSourceRoot
doesn't appear in the public api, there's no method header comment to consult.



--
This message was sent by Atlassian JIRA
(v6.2#6252)

Mime
View raw message