comment on

Yeah, except that none of your examples would work. You have to put blank lines before and after each POD directive. Having an =item with a label, but no text, confuses most processors.

There are a lot of dark corners in POD. I am constantly reminding people when to indent, and when not to. I think POD violates a lot of the DWIM'ness of perl, because a lot of times POD does something really weird. Especially if you forget to put new lines in or something like that.

Today one of my co-workers put a blank space on a line after some pod directive. Well, that doesn't work, but it is not clear why (unless you are using cperl-mode, and have those annoying underscores showing up all over your code). Hey, this isn't Python; whitespace shouldn't matter! :)

That said, I always use POD, because that's all there is. pod2usage is great, too. But I wish we had something like JavaDoc, which is SO much easier to use, and it generates better output, too. Java has a head start as a strongly typed language, of course. But why can't we have =sub, =param, and =return tokens in POD?

-Mike

In reply to Re: difficulty(pod) < difficulty(html) by mulvaney
in thread Documentation by jonjacobmoon

Are you posting in the right place? Check out Where do I post X? to know for sure.
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
Want more info? How to link or How to display code and escape characters are good places to start.


Clear questions and runnable code get the best and fastest answer
	PerlMonks