Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw
 
PerlMonks  

Re: Guidelines for listing functions/methods in POD?

by Your Mother (Bishop)
on Dec 07, 2017 at 21:33 UTC ( #1205119=note: print w/replies, xml ) Need Help??


in reply to Guidelines for listing functions/methods in POD?

The major reason the =head2 style came into vogue, you probably had it recommended to you at some point, is that it gives navigation entries on the CPAN sites for documentation page. So, you can click down to a method easily from the top. I disagree that POD semantics should be disregarded and assert that doing it with =item and such is proper. The fault, to me, lies in the presentation layer (CPAN view), not the data (the POD).

Up to you which is right for you.

Replies are listed 'Best First'.
Re^2: Guidelines for listing functions/methods in POD?
by Anonymous Monk on Dec 07, 2017 at 23:28 UTC
    Pod semantics arent being disregarded.

      I was arguing the semantics are being misused. If you have head1, head2, head3... they correspond to something like book, chapter, verse. A single method or function, to me, never rises to the level of chapter. Item is a much better library match for a function than head2. It's a FOSS world, lots of hackers disagree, do what you like, etc. Promoting list items to chapter titles breaks reasonable semantics in my view and promotes lousy hierarchies and slap-dash documentation. But I will cogitate on your thorough and incisive rebuttal since it contains so much to consider.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1205119]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (4)
As of 2018-11-21 03:58 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My code is most likely broken because:
















    Results (236 votes). Check out past polls.

    Notices?