Bug #52875 for Getopt-Long-Descriptive: Layout of the docs is confusing.

Thu Dec 17 16:11:47 2009 mschwern [...] cpan.org - Ticket created

Subject:

Layout of the docs is confusing.

This was originally entitled "What's the mysterious 3rd argument to describe_options()?" because I didn't see the docs for it. The real problem is that the documentation is laid out sort of like for a program, with major sections pertaining to describe_options(). But then there's also a normal function documentation for describe_options(). My normal algorithm for finding docs for a function is A) look at the SYNOPSIS and then B) search for the function name. This caused me to entirely skip over the actual docs for describe_options(). Then it was compounded by the describe_options() docs saying to go look at the SYNOPSIS which doesn't contain much information.

Sat Mar 13 15:02:45 2010 rjbs [...] cpan.org - Correspondence added

On 2009-12-17 16:11:47, MSCHWERN wrote: Show quoted text

> This was originally entitled "What's the mysterious 3rd argument to > describe_options()?" because I didn't see the docs for it. The real > problem is that the documentation is laid out sort of like for a > program, with major sections pertaining to describe_options(). But then > there's also a normal function documentation for describe_options().

Documentation overhauled: http://search.cpan.org/dist/Getopt-Long-Descriptive/lib/Getopt/Long/Descriptive.pm Is it soup yet? -- rjbs

Sat Mar 13 15:02:49 2010 The RT System itself - Status changed from 'new' to 'open'

Sat Mar 13 15:25:05 2010 schwern [...] pobox.com - Correspondence added

Subject:	Re: [rt.cpan.org #52875] Layout of the docs is confusing.
Date:	Sat, 13 Mar 2010 12:23:42 -0800
To:	bug-Getopt-Long-Descriptive [...] rt.cpan.org
From:	Michael G Schwern <schwern [...] pobox.com>

Ricardo SIGNES via RT wrote: Show quoted text

> <URL: https://rt.cpan.org/Ticket/Display.html?id=52875 > > > On 2009-12-17 16:11:47, MSCHWERN wrote:

>> This was originally entitled "What's the mysterious 3rd argument to >> describe_options()?" because I didn't see the docs for it. The real >> problem is that the documentation is laid out sort of like for a >> program, with major sections pertaining to describe_options(). But then >> there's also a normal function documentation for describe_options().

> > Documentation overhauled: > > http://search.cpan.org/dist/Getopt-Long-Descriptive/lib/Getopt/Long/Descriptive.pm > > Is it soup yet?

Much better. And now nit picking. Add the sigils to the headings for the describe_options() arguments. =head3 $usage_desc, =head3 @opt_spec and =head3 %arg. This allows them to be picked out much easier in the docs, the distinction between head2 and head3 isn't enough. "Getopt::Long::Descriptive only exports one routine" prog_name() makes this a lie. -- Reality is that which, when you stop believing in it, doesn't go away. -- Phillip K. Dick

Sat Mar 13 15:58:07 2010 rjbs [...] cpan.org - Correspondence added

Subject:	Re: [rt.cpan.org #52875] Layout of the docs is confusing.
Date:	Sat, 13 Mar 2010 15:57:06 -0500
To:	Michael G Schwern via RT <bug-Getopt-Long-Descriptive [...] rt.cpan.org>
From:	Ricardo Signes <rjbs [...] cpan.org>

* Michael G Schwern via RT <bug-Getopt-Long-Descriptive@rt.cpan.org> [2010-03-13T15:25:13] Show quoted text

> Much better. > > And now nit picking.

Seasoning added to soup in git. -- rjbs

Sat Mar 13 18:59:53 2010 rjbs [...] cpan.org - Correspondence added

Marking resolved. -- rjbs

Sat Mar 13 18:59:55 2010 rjbs [...] cpan.org - Status changed from 'open' to 'resolved'

Bug #52875 for Getopt-Long-Descriptive: Layout of the docs is confusing.

Preferred bug tracker