Ruby Forum Ruby-core > Uniform RDoc markup

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.

-- Jeremy

--
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

Jeremy McAnally wrote:

>       * parameter  - Explains all parameters if the list can't be
> easily explained in the introduction.

Just as a critique, that's not too DRY. I always want this to work:

   # what foo do
   def foo(
         bar,       #  important because we said so
         baz,       #  also important
         boo = 42)  #  get this one wrong at thy peril

And that would automatically cover the defaults, too...

Now how to do it for option-hash notation?

On 4 May 2008, at 19:05, Phlip wrote:
>        baz,       #  also important
>        boo = 42)  #  get this one wrong at thy peril

But as with all matters of code layout, it's as ugly to some as it is
as beautiful to others.


Ellie

Eleanor McHugh
Games With Brains
http://slides.games-with-brains.net
----
raise ArgumentError unless @reality.responds_to? :reason

"Jeremy McAnally" <jeremymcanally@gmail.com> writes:

> Would there be any resistance to making the markup of the RDoc
> throughout the core code more consistent?

I would be very much in favour of seeing stronger conventions applied
throughout the Ruby community in the standard library, in gems, and
elsewhere. That's one of the things I miss from writing Emacs Lisp; it
has very specific guidelines[1] (The first line should be a summary
under 67 characters, use the active voice for commands, write
metasyntactic variables in caps, etc.) and this is very helpful for
ensuring consistency. In fact, some of the guidelines can even be
checked programmatically[2]. In Ruby we have the mechanics of formatting
explained fairly well, but I believe more suggestions about style and
structure would be helpful.

I think Jeremy's suggestions are good. I would add a clearer distinction
between functions that are called for side-effects and functions that
are called just for their return value, and I would separate out the
parameters section into required, optional, and "options" keyword-style
parameters.

-Phil

[1] - 
http://www.gnu.org/software/emacs/elisp/html_node/Documentation-Tips.html
[2] - http://cedet.sourceforge.net/checkdoc.shtml

On May 4, 2008, at 13:37 , Phil Hagelberg wrote:

> "Jeremy McAnally" <jeremymcanally@gmail.com> writes:
>
>> Would there be any resistance to making the markup of the RDoc
>> throughout the core code more consistent?
>
> I would be very much in favour of seeing stronger conventions applied
> throughout the Ruby community in the standard library, in gems, and
> elsewhere. That's one of the things I miss from writing Emacs Lisp; it
> has very specific guidelines[1]

I guess Phil brings up a good point... emacs lisp doco is a breeze to
read.

I don't mind any work making rdoc more consistent, but I'll resist any
efforts to make it so damn structured. Do we really need to have an h4
tag for the parameters, options, returns, examples sections??? Let's
leave javadoc to the java ppl and do something cleaner and clearer.

Of course.  I just tossed that out there because it makes sense to me,
not that it's the ultimate template.  I based it off of the C#
documentation, since I find it the easiest to navigate.  I know
exactly what I'm looking for will be, which, I think, is a benefit of
it being so structured.

I'm definitely open to an alternate approach.

--Jeremy

On Mon, May 5, 2008 at 2:55 AM, Ryan Davis <ryand-ruby@zenspider.com> 
wrote:
> >
> for the parameters, options, returns, examples sections??? Let's leave
> javadoc to the java ppl and do something cleaner and clearer.
>
>
>



--
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

On May 4, 2008, at 09:13 AM, Jeremy McAnally wrote:

>
>         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.

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@segment7.net> wrote:
> >     ==== Parameters
> >
>
>  class Gem::Dependency
>
>  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

Jeremy McAnally wrote:
> 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.

I suppose this would fall under examples, but the main lack I see in
stdlib is NOT having RDoc *automatically* tell the user what files
they need to require() in order to use the module/class/method they
are reading documentation about.

For instance, how is a newcomer supposed to know that they must
require('thread') in order to get the Queue class?  That particular
case is not even intuitive:  if you try require('queue'), Ruby fails
with a LoadError.

In this manner, it would be tremendously helpful if RDoc
*automatically* supplied a "dependencies" or "prerequisites" section
that specifies:  (1) the file you need to require() in order to get
access to the module/class/method, and (2) the fully qualified path
of the module/class that contains the method they are reading
documentation about (if the documentation is about a method).