Re: Uniform RDoc markup

Right.  The chrome would disappear if it's not necessary.  Only 3
parameters?  No problem.  Just leave off the parameters section.  Same
with options hash.  That was mostly an inflated example to show the
possibilities.

The main lack I see in the stdlib is the lack of examples for a number
of things and some things not being doc'd at all.  The things that are
documented are sort of haphazardly laid out (example, some things have
"= Examples", some have "Here are a few examples:", some have
"Examples:", and so on).  I would like to make those sorts of things
much more uniform to make it even easier to read and navigate.  The
template I suggested was just that: a suggestion.  If you have
something that's more "plain and simple" that still gives things a
uniform, navigable form, then please suggest it.  I'm open to doing it
whatever form people find best.

--Jeremy

On Wed, May 7, 2008 at 6:46 PM, Eric Hodel <drbrain <at> segment7.net> wrote:
> On May 4, 2008, at 09:13 AM, Jeremy McAnally wrote:
>
>
> > Would there be any resistance to making the markup of the RDoc
> > throughout the core code more consistent?  Here's the template I like
> > using:
> >
> >     Introductory material goes here, where I explain the jist of the
> > method and mention a few key parameters if I need to.
> >
> >     ==== Parameters
> >     * parameter  - Explains all parameters if the list can't be
> > easily explained in the introduction.
> >
> >     ==== Options
> >     * option  - Explains all available options, possible values, and
> > default values.
> >
> >     ==== Returns
> >     * Possible return values...
> >     * ...if there are a lot of variants dependent on parameters.
> >
> >     ==== Examples
> >        # A few examples, documented in comments if possible
> >        puts "Howdy!"
> >
> >         # Demonstrate most likely use cases
> >         puts "Hello!"
> >
> > If we could come up with a template that works, I'll gladly go through
> > and start applying it to the standard library and move out from there.
> >
>
>  I prefer plain and simple as it is more pleasant to read than all this
> boilerplate.  Much of the current standard library's documentation is
> pleasant to read as ri (if occasionally densely packed with information,
> like String#split).
>
>  Actually, I can't think of much of the core library that has more than
> three arguments, and none of it that has any hash-style options.
>
>  As a counterpoint, here's some RDoc I just wrote:
>
>  class Gem::Dependency
>
>   ##
>   # Uses this dependency as a pattern to compare to the dependency +other+.
>   # This dependency will match if the name matches the other's name, and
> other
>   # has only an equal version requirement that satisfies this dependency.
>
>   def =~(other)
>     # ...
>   end
>
>  end
>
>  I use consistent ruby vocabulary to describe what this #=~ does without
> using a bunch of boilerplate.
>
>  It may be unclear that you could use a regular expression in the name of a
> dependency, but I have implied that by using "match" instead of "equal".
> The addition of an example might help.
>
>

--

-- 
http://jeremymcanally.com/
http://entp.com

Read my books:
Ruby in Practice (http://manning.com/mcanally/)
My free Ruby e-book (http://humblelittlerubybook.com/)

Or, my blogs:
http://mrneighborly.com
http://rubyinpractice.com