[#2367] Standard libraries — Dave Thomas <dave@...>

From ruby-dev summary:

60 messages 2004/02/11

[#2397] PATCH: deprecate cgi-lib, getopts, importenv, parsearg from standard library — Gavin Sinclair <gsinclair@...>

Index: cgi-lib.rb

15 messages 2004/02/12

[#2465] PATCH: OpenStruct#initialize to yield self — Gavin Sinclair <gsinclair@...>

This is a common approach I use to object initialization; I don't know

24 messages 2004/02/19

Re: Standard libraries

From: "Gavin Sinclair" <gsinclair@...>
Date: 2004-02-12 03:41:28 UTC
List: ruby-core #2378
> Hi,
>
>> From: "Yukihiro Matsumoto" <matz@ruby-lang.org>
>> Sent: Thursday, February 12, 2004 8:28 AM
>
>> Here's the modified version of your criteria, that I can accept:
>>
>>   1. newly added things will be canceled if they are not documented
>>      completely before the stable release.
>
> RDoc style is a must?  I don't like documentation buried within
> a source code (code duplication for me).

RDoc is the standard way to document standard library files.  It's only
code duplication if you put code in the comments :)

> And what do you mean "completely"?  All public
> methods/instance_methods must be documented, right?

My opinion is that all "important" public methods should be documented,
and some top-level introduction and usage examples are given.  For
example, a complicated library like 'soap' may have lots of public methods
that are for internal use only.  If a user never *uses* it, then they
probably don't want to read documentation about it.

Still with 'soap', the SOAP module should have enough documentation to
show the user how to use it.  And they should get an idea of which classes
are important to them, and which ones are not.

I'm always happy to improve the documentation that coders leave behind in
the standard library.  But if there's nothing there for me to get started
with, it's quite difficult.

Cheers,
Gavin



In This Thread