Secret POD docs

petdance has asked for the wisdom of the Perl Monks concerning the following question:

I'm building a module where I want to have documentation for every function, but I want the internal-use-only functions to be ignored by pod2xxx. For instance:

=head2 glarb()

The C<glarb()> function takes care of all your glarbing needs.

=cut

sub glarb() {
    # Do the glarbing
    _glarb_internals();
}

=head2 _glarb_internals()

Does the real work of glarbing.  

=cut

sub _glarb_internals() {
    # Do the interesting stuff
}
[download]

I want to document _glarb_internals() in the same way as any other method, but I don't want it to appear when the user runs pod2html on the file. It's just clutter and is something they shouldn't be calling directly anyway.

Is there something I'm missing in POD?

xoxo,
Andy

%_=split/;/,".;;n;u;e;ot;t;her;c; ".   #   Andy Lester
'Perl ;@; a;a;j;m;er;y;t;p;n;d;s;o;'.  #   http://petdance.com
"hack";print map delete$_{$_},split//,q<   andy@petdance.com   >

Comment on Secret POD docs Download Code

Replies are listed 'Best First'.
Re: Secret POD docs by merlyn (Sage) on May 07, 2001 at 17:55 UTC
If it's not POD and it's not code, perhaps you just want a fat comment, using POD triggers, as in: `=head2 glarb() The C<glarb()> function takes care of all your glarbing needs. =cut sub glarb() { # Do the glarbing _glarb_internals(); } =begin INTERNAL_USE_ONLY _glarb_internals(...) Does the real work of glarbing. =end INTERNAL_USE_ONLY =cut sub _glarb_internals() { # Do the interesting stuff }` [download] -- Randal L. Schwartz, Perl hacker	[reply] [d/l]
Re: Re: Secret POD docs by frag (Hermit) on May 07, 2001 at 19:49 UTC
Along the same lines: `=begin private _benjamin(...) Movie starring Goldie Hawn. =end private` [download] Not like there's any functional difference, but I've always found `=for` to be a bad choice, both esthetically and because I think it'd be confusing to future maintainers, who may not immediately get what you're doing here. Also, according to perlpod you're misusing `=for` in that example. There shouldn't be a blank line between the `=for FOO` and the POD you're for'ing. pod2html, for instance, will let the 'private' POD be displayed if you do that. Also, `=for` doesn't take an `=end`, which will also kill pod2html/Pod::Html with the error "Unmatched begin/end". (At least, it will for version 1.02 that comes with the Perl 5.005.03 that I'm using right now...) Update: There is one functional difference that bears mentioning: using begin/end like this will let you hide multiple paragraphs. (Update #2: cleaned up some confusing word choices in one sentence, that I just couldn't stand to let stand.) -- Frag.	[reply] [d/l]
Re: Re: Secret POD docs by petdance (Parson) on May 07, 2001 at 19:37 UTC
The bummer here is that the `=for` only works for the next paragraph. In the example above, the 2nd line ("Does the real work of glarbing") would still show up. xoxo, Andy %_=split/;/,".;;n;u;e;ot;t;her;c; ". # Andy Lester 'Perl ;@; a;a;j;m;er;y;t;p;n;d;s;o;'. # http://petdance.com "hack";print map delete$_{$_},split//,q< andy@petdance.com >	[reply]
Re: Secret POD docs by Rhandom (Curate) on May 07, 2001 at 18:00 UTC
UPDATE: Merlyn's code above out does what I say here! Listen to merlyn. I know of no secret pod tags, but you could use a pod hack like the following. I wouldn't recommend it, but it does allow for you to hide at least one line from the pod. The basic premise is -- use a bogus tag and the the perl parser will treat it like but pod parser will ignore it. Anything on the same line as that bogus tag will also get ignored. Not good in wide practice. `#!/usr/bin/perl -w =head1 Some function or other =cut sub foo { } =bogustag1 Yet Another function 1 =cut sub foo2 { } =bogustag2 Yet Another function =cut sub foo3 { }` [download] What was wrong with using "#"'s again? my @a=qw(random brilliant braindead); print $a[rand(@a)];	[reply] [d/l]
Re: Re: Secret POD docs by petdance (Parson) on May 07, 2001 at 19:39 UTC
What was wrong with using "#"'s again? I don't want to code my docs differently depending on whether the docs will be visible to the outside world or not. xoxo, Andy %_=split/;/,".;;n;u;e;ot;t;her;c; ". # Andy Lester 'Perl ;@; a;a;j;m;er;y;t;p;n;d;s;o;'. # http://petdance.com "hack";print map delete$_{$_},split//,q< andy@petdance.com >	[reply]
Re: Re: Re: Secret POD docs by merlyn (Sage) on May 07, 2001 at 19:43 UTC
You've now got conflicting requirements. Can you step back and specify what you want, instead of potshotting at the solutions because it's what you don't want? If you want pod tools that have an ifdef, you'll need to write them. If you want existing pod tools to work, you'll need to code your internal stuff as non-POD. There's no "third solution". -- Randal L. Schwartz, Perl hacker	[reply]