|
Re: Documenting non-public OO components
by Zaxo (Archbishop) on Sep 06, 2005 at 15:59 UTC
|
You can place your internal methods in a Foo::Devel package which acts as a helper module and has its own pod. That will seperate both them and their documentation from the public, while leaving them accessible to all.
From the sound of it, your modules seem pretty tightly bound to each other. Could a redesign produce a more natural split of responsibilities?.
| [reply] |
|
|
Well, the big project I'm working on is an overhaul of Plucene, the perl port of the Java Lucene search engine library http://lucene.apache.org/. I'm moving a couple things around, but for the most part it should stay as is, and Lucene's pretty well designed.
Beyond that, I'm not sure that it makes sense to constrain development via a severe public-class-all-things-public / devel-class-all-things-devel split. You could do that, but there are bound to be occasions when you wish you could add a protected method to that public class. For sure, it's a good idea to divide responsibility, but unless you take draconian measures, the problem still exists.
| [reply] |
Re: Documenting non-public OO components
by xdg (Monsignor) on Sep 06, 2005 at 16:14 UTC
|
Read the docs for Pod::Coverage. You can easily specify additional items to consider private and not needing coverage with also_private. If you don't want to take that extra step, just document them as public or private in the pod, either inline -- or better yet -- in sections marked "PUBLIC METHODS", "PRIVATE METHODS" etc.
-xdg
Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.
| [reply]
[d/l] |
|
|
| [reply] |
Re: Documenting non-public OO components
by japhy (Canon) on Sep 06, 2005 at 15:52 UTC
|
I put my POD at the end of all my code, so I can document things in an order not necessarily found in my code. To this end, I would document the public methods in one group, then the protected in another.
| [reply] |
|
|
=head1 SYNOPSIS
No public interface
However, it would be nice to put something in the SYNOPSIS section, even for a devel class. PRIVATE SYNOPSIS / PUBLIC SYNOPSIS ?
| [reply]
[d/l] |
|
|
In the synopsis, I would probably be just about as terse as your example; but perhaps a small example would help. I would at least explain the class's purpose in its description, though.
| [reply] |
Re: Documenting non-public OO components
by siracusa (Friar) on Sep 07, 2005 at 02:26 UTC
|
I recently faced a similar problem: methods that are meant to be used by subclasses, but not by "the public." You can see my solution on CPAN. I created a separate "PROTECTED API" section, and I explained what I meant by "protected" in the "DESCRIPTION" section. I'm not particularly happy with this solution, but at least it's explicit.
| [reply] |
|
|
I may end up doing something akin to that. Since Plucene is a large library, I can put the explanation in one central place (probably the main module), then hew to the convention elsewhere. That's way better than what I was considering before; it's nice to see your example.
| [reply] |
Re: Documenting non-public OO components
by lachoy (Parson) on Sep 06, 2005 at 16:53 UTC
|
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.
| [reply] |
|
|
| [reply] |
|
|
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: Documenting non-public OO components
by educated_foo (Vicar) on Sep 07, 2005 at 05:03 UTC
|
Perl actually has infiniti levels of access -- just name them and document them! Access control is no substitute for documentation and self-discipline. | [reply] |
|
|
Freedom isn't free.
It's a PITA to figure out how to convey public/package/protected/private when the code CAN'T self-document because access control levels aren't part of the language. Not having those constraints in Perl allows all kinds of wacky OO structures (for better and worse), but there's no easy, efficient, widely understood ACL-documenting convention in Perl besides the leading underscore, and that's totally inadequate for large systems consisting of dozens of classes.
It would be nice if I didn't have to reinvent this wheel. I strive to be one of those people who can assess the strengths and weaknesses of various languages without descending into polemics and bigotry; I humbly submit that while the straight-jacket Java imposes causes other problems, it sure does make documenting ACLs a lot easier than good-ol'-anything-goes Perl. As a consequence, I have less time to spend on other things, and I don't like that.
| [reply] |
Re: Documenting non-public OO components
by dragonchild (Archbishop) on Sep 08, 2005 at 13:14 UTC
|
Should private methods be documented in the test suite and public methods documented in the POD? Or, am I missing something?
My criteria for good software:
- Does it work?
- Can someone else come in, make a change, and be reasonably certain no bugs were introduced?
| [reply] |
|
|
I assume that you refer to the technique of documenting the functionality of a module indirectly by providing tests which double as example code, labeled by a message which indicates what the test is for. That is certainly useful as a supplement, but not as a substitute for the summary of functionality that typically appears in POD or javadocs.
If you were trying to grok the flow of data through several classes, and through perhaps 10 or 20 methods, would you prefer dredging the intended use for each method out of the test code over consulting a purpose-built summary? I think you would have a hard time achieving the level of confidence required by the second test in your sig. Bad software! Bad! :)
| [reply] |
|
|
If you were trying to grok the flow of data through several classes, and through perhaps 10 or 20 methods, . . .
Lord and Lady preserve us! How complicated are you making your code?! If I have to do what you're suggesting, that is a CodeSmell and needs to be addressed immediately, preferably through refactoring the living #$E*! out of it. I should be able to look at a test and see exactly how I'm supposed to use any portion of your code. Period, end of story. Otherwise, either your tests or your design sucks. (Or both, but if that's the case, then you're better off starting from scratch.)
Remember - we're talking about the non-public portions of your API. This is the stuff that you don't want the average client using. Since the intended audience is a developer, they should be looking through the tests, anyways, to understand the assumptions you've made that your code won't document. In addition, they probably are looking through your tests in order to figure out how to test their modifications to or subclass of your stuff.
Furthermore, I'll point at DRY (Don't Repeat Yourself). A purpose-built summary is, by definition, a repetition. It has to be kept in sync by hand and thus, by definition, won't be in sync. The tests, on the other hand, are part and parcel of the code in question. If the test suite passes (as it always should), then I know that the tests are the best possible form of documentation the developer could have provided. (They're even better than any comments that might be in the code.)
While we're on the topic, the documentation for the public API should consist of the following:
- What is this thing (NAME)
- Basic usage (SYNOPSIS)
- Ideas behind it (DESCRIPTION)
- Details about the names of the methods and the various options (METHODS)
- Common uses (EXAMPLES)
- Anything else the client should know (BUGS/CAVEATS)
- How to get more help (CONTACTS/AUTHORS)
No more and no less. (Any similarity to the standard POD skeleton is completely intentional.) At no time should any reference be made to implementation details, save when one public method calls another public method within the same module (and that should be done sparingly). Private methods should never appear, save when they violate some community contract (such as having "new" or "clone" be a private method) or some Perlism (such as having "print" be a private method). And, frankly, if you have to document a private method in your public API, that's a DesignSmell and should be addressed ASAP.
My criteria for good software:
- Does it work?
- Can someone else come in, make a change, and be reasonably certain no bugs were introduced?
| [reply] |
|
|
|
|
|
Re: Documenting non-public OO components
by petdance (Parson) on Sep 09, 2005 at 00:44 UTC
|
| [reply] |
|
|
What about methods, typically called "package" or "protected", which are not part of the public API, but must be called by other classes that are part of the distro? Those should not have leading underscores, IMO, because it contradicts standard practice. From perlstyle:
You can use a leading underscore to indicate
that a variable or function should not be used
outside the package that defined it.
The Pod::Coverage problem is solvable with minimal effort, as both you and xdg have pointed out (thanks). However, there is still the need to document these methods while indicating clearly that they are not available to users.
There seems to be a range of opinion on as to the best solution. The ones that I like best for this project at least are the ones closest to javadoc, but I can appreciate the merits of the document-by-test and the bury-private-docs-deeply schools as well.
| [reply]
[d/l] |
|
|
=head1 Public methods
=head2 $obj->wango
=head2 $obj->doofus
=head1 Internal-only methods
=head2 $obj->whatever
| [reply]
[d/l] |