A couple months ago, RJBS and I collaborated on adding a new feature to Pod: sane URL links. For, well, ever, the case has been that to link to URLs or any other scheme: links in Pod, You had to do something like this:

For more information, consult the pgTAP documentation:
L<https://pgtap.org/documentation.html>

The reasons why you couldn’t include text in the link to server as the link text has never been really well spelled-out. Sean Burke, the most recent author of the Pod spec, had only said that the support wasn’t there “for various reasons.”

Meanwhile, I accidentally discovered that Pod::Simple has in fact supported such formats for a long time. At some point Sean added it, but didn’t update the spec. Maybe he thought it was fragile. I have no idea. But since the support was already there, and most of the other Pod tools already support it or want to, it was a simple change to make to the spec, and it was released in Perl 5.11.3 and Pod::Simple 3.11. It’s now officially a part of the spec. The above Pod can now be written as:

For more information, consult the
L<pgTAP documentation|https://pgtap.org/documentation.html>.

So much better! And to show it off, I’ve just updated all the links in SVN::Notify and released a new version. Check it out on CPAN Search. See how the links such as to “HookStart.exe” and “Windows Subversion + Apache + TortoiseSVN + SVN::Notify HOWTO” are nice links? They no longer use the URL for the link text. Contrast with the previous version.

And as of yesterday, the last piece to allow this went into place. Andy gave me maintenance of Test::Pod, and I immediately released a new version to allow the new syntax. So update your t/pod.t file to require Test::Pod 1.41, update your links, and celebrate the arrival of sane links in Pod documentation.

Looking for the comments? Try the old layout.

Is there a JavaScript documentation standard? I’ve been working on a test framework for JavaScript and I’d like to integrate documentation so that others can use it.

If there isn’t a documentation standard, I can see three possible options that I’d like to suggest:

Use XHTML.

Since JavaScript is mainly used for XHTML, it makes some sense to just use XHTML for its documentation. The downside to this is that there is currently no way to parse out the documentation, AFAIK. The format for putting the docs into comments would have to be standardized. I don’t really see that happening.

Use POD.

JavaScript is a dynamic language; it’d make some sense to use the documentation format of an existing dynamic language. And POD is a proven format. The downside, of course, is that there is not a parser for pulling POD out of a .js file. Same problem as for XHTML, essentially.

Use JavaDoc

Since the syntax of JavaScript is roughly based on JavaScript, and JavaScript supports the same comment syntax, one could simply use the JavaDoc format. The javadoc application probably couldn’t parse it out too well, since it parses the Java code (or byte code?) to automatically document method names, signatures, etc.

But a quick Googling yields JSDoc as a possible solution. The only downside to the JavaDoc/JSDoc solution is that it tends to allow authors to be too lazy. Since the application automatically documents the existence of functions and their signatures, often little else is documented. But that’s mainly a personal issue; I don’t have to be so lazy in my own documentation! I think I’ll give that a shot.

Meanwhile, if anyone knows of something better/more widely used, let me know!

Looking for the comments? Try the old layout.