Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

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.

Chris
M-x auto-bs-mode


Comment on Re: Documenting non-public OO components
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 ― http://www.rectangular.com

      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 ― http://www.rectangular.com

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others having an uproarious good time at the Monastery: (13)
As of 2014-12-20 17:00 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (96 votes), past polls