Re: POD question: listing methods

So, I changed some of them to just listing the method name in the headline, and put a illustrative parameter list and return value on the next line as a verbatim paragraph.

What's a better way to do it?

Actually, I think that is the better way of doing it :-) After some experimentation with various formats I've standardised on something like:

=item B<foo>

  $object->foo
  $object->foo($bar)

Do foo to $object using $bar, or undef if $bar is not specified.
[download]

The advantages for me are:

I find it quite clear.
You don't have to re-write indices/TOCs if you tweak the calling examples.
It resolves the ambiguities of having multiple =item statements when you have multiple ways of calling a function.

Comment on Re: POD question: listing methods Download Code

Replies are listed 'Best First'.
Re: Re: POD question: listing methods by John M. Dlugosz (Monsignor) on Oct 30, 2002 at 00:34 UTC
Why use a bold tag around the item, too? Does that just look better on some particular translation? In my documentation style that I've used in TeX and other formats, I found making the function name alone as a very noticable thing on the page is a good idea. This follows the same principle. I see, although Perl doesn't have overloading like C++, it still has multiple ways to call something that ought to be illustrated.	[reply]
Re^3: POD question: listing methods by adrianh (Chancellor) on Oct 30, 2002 at 10:47 UTC
Why use a bold tag around the item, too? Does that just look better on some particular translation? Yup. I find it makes it easier to spot methods when you're scrolling through a long document.	[reply]