Re: documentation best practices for internal modules

I'm with the others; document everything. Because that's been covered, I'll leave it alone.

If you don't want your internal modules/subs being used by external code, you can catch that. Here's a rudimentary example:

use warnings;
use strict;

package Internal; {
    sub foo {
        my $caller = (caller(1))[3];
        my $me = (caller(0))[3];
        if ($caller !~ /^Internal::/){
            die "$me is only available internally\n"
        }

        ...
    }
}
package External; {
    sub bar {
        Internal::foo();
    }
}

package main;

External::bar();

__END__
Internal::foo is only available internally
[download]

Comment on Re: documentation best practices for internal modules Download Code

Replies are listed 'Best First'.
Re^2: documentation best practices for internal modules by Anonymous Monk on Jan 08, 2018 at 22:44 UTC
If you don't want your internal modules/subs being used by external code, you can catch that. Abide by the ethos? Why assume you're smart enough to know what your users are paying for today/tomorrow? This is all the checks you need `=head1 FOR INTERNAL USE ONLY This is private api for internal use only, it can change at any time, +standard disclaimers apply, use at your own risk.... =cut` [download]	[reply] [d/l]

Replies are listed 'Best First'.

Re^2: documentation best practices for internal modules
by Anonymous Monk on Jan 08, 2018 at 22:44 UTC

If you don't want your internal modules/subs being used by external code, you can catch that.

Abide by the ethos?

Why assume you're smart enough to know what your users are paying for today/tomorrow?

This is all the checks you need

=head1 FOR INTERNAL USE ONLY

This is private api for internal use only, it can change at any time, 
+standard disclaimers apply, use at your own risk....

=cut
[download]

[reply]
[d/l]