Recently I needed to extend the documentation in one of our projects, which used Perl on the server and JavaScript in the browser. This reminded me of a throwaway comment I’d seen online about using Plain Old Documentation (POD) in languages other than Perl.

As the server side of the project is written in Perl it made sense to try using POD in both the Perl and the JavaScript. Sure enough, as long as you wrap your POD in /* block comments */, then it works perfectly. e.g.

/*
=head1 NAME

Pointless Example - a pointless example of using POD in JavaScript

=head1 FUNCTIONS

=head2 HelloWorld(message)

An example of POD for a function

=head3 PARAMETERS

=over 4

=item I

The message

=back

=head3 RETURNS

Returns the message preceded by "e;Hello World"e;

*/

function HelloWorld(message) {
    return "Hello World " + message;
}

The main advantage of using POD in this case is that all my documentation can be rendered by the same process, irregardless of whether it is for the backend Perl code or frontend JavaScript.