Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Perl has this really cool documentation method that makes documenting really easy. It's called POD (Plain Old Documentation). Here is an example:

=head1 NAME

Example::Module - an example

=head1 SYNOPSIS

    use Example::Module;
    my $object = Example::Module->new();
    print $object->as_string;

=head1 DESCRIPTION

Just an example.

=head2 Methods

=over 12

=item C<new>

Returns a new My::Module object.

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=back

=head1 LICENSE

This is released under the Artistic 
License. See L<perlartistic>.

=head1 AUTHOR

Dynamic 

=head1 SEE ALSO

L<perlpod>

=cut

The output of this would be in HTML, like this example on CPAN (not what I wrote). Cool right!

So is there a method similar to POD in which a developer can put there documentation inside of the code itself, without it being a comment?

share|improve this question

1 Answer 1

up vote 4 down vote accepted

JavaDocs are very similar to this. They are comments but they are a special form of comment that are then compiled to produce documents that look like the official Java documentation.

Both JavaDoc and POD are examples of "Documentation Generators" of which there are many. Wikipedia has a good sized list for a variety of platforms and languages.

share|improve this answer
    
I would like to point out that there has been at least one published book written in a variant of POD. * –  Brad Gilbert May 16 '12 at 5:04

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.