Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Greets,

In Java, there are four levels of access: public, package, protected, and private. In Perl, there are effectively two: public, and leading-underscore-private. Unfortunately, the leading underscore is generally understood to mean won't-be-used-outside-this-file, and just because you can break this convention doesn't mean it's a good idea.

In putting together multi-module distros, I have lots of methods, variables, and whole classes which have to be accessed by other classes, and so shouldn't get the leading-underscore treatment -- but they aren't part of the public API. In Java, these would get tagged as package or protected as part of the declaration, making the code self-documenting. Since Perl imposes fewer rules, the only way to indicate that such a component isn't public is to document it as such explicitly.

I'd like to use POD to document these components, but if something's in POD and it doesn't have a leading underscore, the implication is that it's public. So what are the alternatives?

Mark every single component with its access level in the POD? That's verbose, messy and hackish. Nobody does this, for good reason.

Document only with comments? But POD is so much better for long explanations.

Surround =headX tags with =begin comment and =end comment? What a waste of space.

The only thing that seems to make sense is to use =begin comment and =end comment to surround the docs and omit =headX ... =cut. This breaks POD::Coverage, which I don't like at all. Also, this stuff really does belong in extracted documentation -- just with an indication that the documentation is for developers, not users.

Who's got a better way?

--
Marvin Humphrey
Rectangular Research ― http://www.rectangular.com

In reply to Documenting non-public OO components by creamygoodness

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (3)
As of 2022-12-08 02:10 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?