Documentation practices

I've noticed that the POD for several modules do not include method
usage for the functions/methods that are designed as 'internal-only'.

I've reached a stage where not having POD for ALL of my methods is
becoming overwhelmingly cumbersome, as I have to read the code to
remember usage.

Is there a common practice for this? If POD doesn't display internal sub
usage, where would one document it?

Steve

--
To unsubscribe, e-mail: beginners-unsubscribe@perl.org
For additional commands, e-mail: beginners-help@perl.org
http://learn.perl.org/

Re: Documentation practices

Steve Bertrand wrote:
> I've noticed that the POD for several modules do not include method
> usage for the functions/methods that are designed as 'internal-only'.
>
> I've reached a stage where not having POD for ALL of my methods is
> becoming overwhelmingly cumbersome, as I have to read the code to
> remember usage.
>
> Is there a common practice for this? If POD doesn't display internal sub
> usage, where would one document it?
>
> Steve
>

I have two levels of documentation. I have an internal one use for
notes about the implementation for the maintainers of the sub. I have
an external one which describes how to use the sub. Normally, I don't
bother with the second unless I'm writing a module or object.

I use Sub::Starter
http://search.cpan.org/~shcorey/Sub-Starter-v1.0.6/lib/Sub/S tarter.pm
or, to be precise, the script that is installed with it, substarter
http://search.cpan.org/~shcorey/Sub-Starter-v1.0.6/script/su bstarter to
create my sub's from a usage statement and a template. I find creating
a usage statement is easier that creating the sub.

Example:

sub -c '$text | @text = trim( @text );'

This will create;

# --------------------------------------
# Name: trim
# Usage: $text | @text = trim( @text );
# Purpose: TBD
# Parameters: @text -- TBD
# Returns: $text -- TBD
# @text -- TBD
#
sub trim {
my @text = @_;
my $text = '';

return wantarray ? @text : $text;
}


PS: If you're using ViM, you can use substarter as a filter. In ViM,
enter :help filter


--
Just my 0.00000002 million dollars worth,
Shawn

Programming is as much about organization and communication
as it is about coding.

I like Perl; it's the only language where you can bless your
thingy.

--
To unsubscribe, e-mail: beginners-unsubscribe@perl.org
For additional commands, e-mail: beginners-help@perl.org
http://learn.perl.org/

Re: Documentation practices

On 11/24/09 Tue Nov 24, 2009 11:09 AM, "Steve Bertrand"
scribbled:

> I've noticed that the POD for several modules do not include method
> usage for the functions/methods that are designed as 'internal-only'.
>
> I've reached a stage where not having POD for ALL of my methods is
> becoming overwhelmingly cumbersome, as I have to read the code to
> remember usage.
>
> Is there a common practice for this? If POD doesn't display internal sub
> usage, where would one document it?

I would think that you would only include in POD the information needed by
the users of the modules. This would include the external interface, sample
calls, etc. For documenting the internal interfaces, I would add comments in
the code.



--
To unsubscribe, e-mail: beginners-unsubscribe@perl.org
For additional commands, e-mail: beginners-help@perl.org
http://learn.perl.org/

Re: Documentation practices

2009/11/24 Steve Bertrand :
> I've noticed that the POD for several modules do not include method
> usage for the functions/methods that are designed as 'internal-only'.
>
> I've reached a stage where not having POD for ALL of my methods is
> becoming overwhelmingly cumbersome, as I have to read the code to
> remember usage.
>
> Is there a common practice for this? If POD doesn't display internal sub
> usage, where would one document it?

This documentation is clearly necessary, but not for the users of your
module. What you do is document it in such a way that the users never
see it, only the maintainers.

There are several ways to do it. The most common is just a series of #
comments. There are ways to do it in pod but without making it visible
to the users:

=for Rationale:
This function uses Smith's algorithm instead of Jones's. Jones's is
faster in the general case but Smith's performed better when
benchmarked with our test dataset.

=cut

This pod block will not be visible to the users, because it uses the
=for pod directive which means "only for the named pod translator".
There is no translator called Rationale: and so no translator will
read it.

The =begin and =end pod directives can serve a similar purpose.

Phil

--
To unsubscribe, e-mail: beginners-unsubscribe@perl.org
For additional commands, e-mail: beginners-help@perl.org
http://learn.perl.org/