search

ruby / set

This library provides the Set class, which deals with a collection of unordered values with no duplicates.
BSD 2-Clause "Simplified" License
23 stars 13 forks source link

Adding section: What's Here #16

Closed BurdetteLamar closed 3 years ago

BurdetteLamar commented 3 years ago

Categorized summary of methods.

BurdetteLamar commented 3 years ago

@knu, will you be looking at this? If not, can you suggest another reviewer?

BurdetteLamar commented 3 years ago

This seems mostly fine to me, other than changing the linking to use rdoc-ref. However, it probably should be reviewed and approved by @knu.

I agree that it should be reviewed and approved by @knu.

BurdetteLamar commented 3 years ago

Oh, and thanks, @jeremyevans.

BurdetteLamar commented 3 years ago

This approach still depends on the specific rdoc generator in use generating ids in a specific format. It would break with an rdoc generator that used a different format. As I already mentioned, rdoc-ref usage seems more appropriate here.

Note that the same issue applies to the internal links to the headings (e.g. Creating a Set). However, rdoc-ref cannot handle those cases, and I guess the links are better than not linking at all.

I don't think I need to review this again, it's up to @knu whether or not to accept it.

I'm not familiar with rdoc-ref. Will study it, and thanks.

BurdetteLamar commented 3 years ago

Marking as draft while I look at rdoc-ref usage.

BurdetteLamar commented 3 years ago

@BurdetteLamar If I've already said "I don't think I need to review this again", please do not mark me as a reviewer again.

Sorry, I was trying to take you off.

BurdetteLamar commented 3 years ago

@knu, I think this is ready for you.

knu commented 3 years ago

I'm assuming, or hoping that the method names are clear enough in meaning and all you need is the well organized list of methods!

BurdetteLamar commented 3 years ago

This is nice, but I'm not sure if we should duplicate the descriptions and have two mostly identical sentences for each method. Wouldn't it suffice just to list methods with links in the table of contents?

Thanks, @knu. I'd like to leave the 1-liners in. I think it's in the nature of a summary to be repetitive. Also, this format is consistent with the "What's Here" sections for other classes, which I've worked on with @jeremyevans and @marcandre: