Suggestions for RDoc

[Nikolai Weibull]

I have two suggestions for RDoc fixes:

1. Object#[] doesn't get documented, at least not in C sources.

2. Could the parser perhaps drop folding-markers from the source? An
example comment with a folding-marker would be:

/* {{{1
*
* call-seq:
* ...
*/

The documentation looks rediculous when these are included. A
solutions is to separate the marker from the documentation:

/* {{{1 */
/*
* call-seq:
* ...
*/

but it still seems, to me, that RDoc could take care of removing
them.

A regex to match folding-markers with could be expressed like:

/(?:{{{|}}})\d*/

It's pretty standard.

Perhaps a good solution to #2 is to allow project-specific inclusions of
parsers. What do you think?,
nikolai

 

[Eric Hodel]

--Apple-Mail-15--369267709
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset=US-ASCII; format=flowed

I have two suggestions for RDoc fixes:

1. Object#[] doesn't get documented, at least not in C sources.

$ ruby
Object.new.[]
-:1: undefined method `[]' for #<Object:0x133bd4> (NoMethodError)

Unless I'm confused, I don't think there is an Object#[].

Array::[] is RDoc'd.

The Array creation syntax [] and [5, 6] is done by the
parser/interpreter. This makes an inline Array which is built by
eval.c, so there isn't an equivalent method call on the Ruby side:

$ parse_tree_show -f
array1 = []
array2 = [5, 6, 7]
[snip]
[:lasgn, :array1, [:zarray]],
[:lasgn, :array2, [:array, [:lit, 5], [:lit, 6], [:lit, 7]]]

NODE_ZARRAY is an empty array, while NODE_ARRAY is used to construct a
new Array object.

A method call looks like this, where the NODE_ARRAY node is used for
the argument list:

$ parse_tree_show -f
1 + 1
[snip]
[:call, [:lit, 1], :+, [:array, [:lit, 1]]]

--
Eric Hodel - (e-mail address removed) - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

--Apple-Mail-15--369267709
content-type: application/pgp-signature; x-mac-type=70674453;
name=PGP.sig
content-description: This is a digitally signed message part
content-disposition: inline; filename=PGP.sig
content-transfer-encoding: 7bit

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (Darwin)

iD8DBQFCOcO+MypVHHlsnwQRAmcxAJ4gdCxB3gNTXgh34tkMJD7i78p2LQCbBr4k
8WwJo0IKvhQsgbHg2C8fAwg=
=pfbP
-----END PGP SIGNATURE-----

--Apple-Mail-15--369267709--

 

[Nikolai Weibull]

* Eric Hodel (Mar 17, 2005 19:00):

1. Object#[] doesn't get documented, at least not in C sources.

$ ruby Object.new.[] -:1: undefined method `[]' for #<Object:0x133bd4>
(NoMethodError)

Badly written, sorry. Object was supposed to be <object>, as in any
object, not necessarily an instance of the Object Class. I don't know
what I was thinking when I wrote it. What I meant was that it doesn't
get linked in a description text for a method, i.e.,

/*
* call-seq:
* ...
*
* Blah, blah, PieceTree#[], blah, blah, ...
*/

The 'PieceTree#[]' doesn't wind up as a reference to that method,
nikolai