Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

Re: Documenting non-public OO components

by lachoy (Parson)
on Sep 06, 2005 at 16:53 UTC ( #489607=note: print w/ replies, xml ) Need Help??

in reply to Documenting non-public OO components

I don't think private methods should be documented in POD at all, otherwise they're not really private. Inline comments for people actually working on the code should be sufficient.

I tend to group 'protected' methods in a POD heading called 'SUBCLASSING' or something similar -- basically, "Here's what you can use and what you need to know to write a subclass", which is what protected methods are really for.

M-x auto-bs-mode

Comment on Re: Documenting non-public OO components
Replies are listed 'Best First'.
Re^2: Documenting non-public OO components
by creamygoodness (Curate) on Sep 06, 2005 at 17:24 UTC

    If I see the heading "SUBCLASSING", that indicates to me that all the information below is public, so I can write my own subclass. Am I missing something?

    Marvin Humphrey
    Rectangular Research ―

      In Java speek 'private' means only the class that declaired it can use it, 'public' means any one of any class can use it. Java also has the notion of 'protected' and 'package', basicly any subclass has access and any class in the same package has access respectivly.

      The "SUBCLASSING" section would declair 'protected' (by convention only) methods. So it would not truely be 'public' in the sense of any class may call them, but it could be seen as 'public' in the sense that you have published their specs for all to see.

        My main concern is to indicate which parts of the libary non-developers may depend upon and which parts they must avoid using. I suppose it is true that any protected or even package components may be accessed if you hack your class just right in Java, but the presence of a protected method in a class which is not explicity intended to be subclassed would not lead me to believe that it was OK to subclass it.

        The problem that I have with a "SUBCLASSING" heading is that, if it's present it seems to indicate that the library allows users, not just developers, to subclass that class. That wouldn't always be the case.

        Marvin Humphrey
        Rectangular Research ―

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://489607]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others taking refuge in the Monastery: (11)
As of 2015-10-13 19:27 GMT
Find Nodes?
    Voting Booth?

    Does Humor Belong in Programming?

    Results (314 votes), past polls