Re: Documenting non-public OO components

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

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 ― http://www.rectangular.com	[reply]
Re^3: Documenting non-public OO components by Ven'Tatsu (Deacon) on Sep 06, 2005 at 18:39 UTC
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.	[reply]
Re^4: Documenting non-public OO components by creamygoodness (Curate) on Sep 06, 2005 at 19:08 UTC
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	[reply]
Re^5: Documenting non-public OO components by lachoy (Parson) on Sep 06, 2005 at 19:43 UTC
Re^5: Documenting non-public OO components by revdiablo (Prior) on Sep 07, 2005 at 15:49 UTC
Re^6: Documenting non-public OO components by creamygoodness (Curate) on Sep 08, 2005 at 00:17 UTC

In Section Meditations