headers
Jeremy McAnally | 4 May 18:10
Picon
Gravatar

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
(Continue reading)

Permalink | Reply |
headers
Phlip | 4 May 20:05
Picon

Re: Uniform RDoc markup

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?

--

-- 
   Phlip
Permalink | Reply |
headers
Eleanor McHugh | 4 May 21:23

Re: Uniform RDoc markup

On 4 May 2008, at 19:05, Phlip wrote:
> 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

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
Permalink | Reply |
headers
Phil Hagelberg | 4 May 22:37
Gravatar

Re: Uniform RDoc markup

"Jeremy McAnally" <jeremymcanally <at> 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
Permalink | Reply |
headers
Ryan Davis | 5 May 08:55
Favicon

Re: Uniform RDoc markup


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

> "Jeremy McAnally" <jeremymcanally <at> 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.
Permalink | Reply |
headers
Jeremy McAnally | 5 May 14:28
Picon
Gravatar

Re: Uniform RDoc markup

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 <at> zenspider.com> wrote:
>
>  On May 4, 2008, at 13:37 , Phil Hagelberg wrote:
>
>
> > "Jeremy McAnally" <jeremymcanally <at> 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.
>
(Continue reading)

Permalink | Reply |
headers
Eric Hodel | 8 May 00:46
Favicon
Gravatar

Re: Uniform RDoc markup

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.
(Continue reading)

Permalink | Reply |
headers
Jeremy McAnally | 8 May 02:23
Picon
Gravatar

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
(Continue reading)

Permalink | Reply |
headers
Suraj N. Kurapati | 8 May 17:54
Picon

Re: Uniform RDoc markup - automatic require() section

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).
Permalink | Reply |

Gmane