search

zapnap / rdocinfo

New development has moved to http://github.com/lsegal/rubydoc.info
http://rdoc.info
MIT License
18 stars 3 forks source link

Why not sort methods alphabetically? #23

Closed dadooda closed 14 years ago

dadooda commented 14 years ago

Hi

I'd proposed strict alphabetical sorting of methods, regardless of which documented class/module they are in.

Most probably, the person knows method name, not class name (which can be too way hairy).

What do you think?

jeffrafter commented 14 years ago

I wonder what lsegal's reasoning behind not alphabetizing was to begin with?

zapnap commented 14 years ago

This would be a feature of the custom template we need to work on, I suspect.

lsegal commented 14 years ago

Actually.. they are sorted alphabetically-- sort of. Methods are grouped by class then sorted alphabetically, that way methods from class X stay near other methods from class X. This seemed to be a good idea at the time (I still think it is).

The sorting of class names used to group the methods is completely random, though... not sure if that really matters.

dadooda commented 14 years ago

Consider an example. You are developing an RSpec for your code and the only thing you remember since last RSpec session is that some matchers contain the word "be".

Here's rdoc: http://rdoc.info/projects/dchelimsky/rspec

Now go try locate those matchers. If the list was alphabetical, that might be easier.

And, in my humble oppinion, class names really mean nothing in cases like this. As for me, I was really never interested what RSpec classes are as long as I'm not involved in RSpec contribution.

ryanb commented 14 years ago

Big +1 to sorting alphabetically. It's pretty much my only problem with rdoc.info. This really is an issue on bigger projects because otherwise it's very difficult to find a specific method.

I rarely know the class/module name of the method I'm looking for, and if I do it's easy enough to click on the class to get a list of methods there. I'm not sure what advantage sorting by class provides over clicking it.

Otherwise great work on RDoc.info, keep it up!

ryanb commented 14 years ago

Any status on this? Would love to see it implemented. Would it happen faster if I submitted a pull request?

zapnap commented 14 years ago

@ryanb -- Since the docs are actually generated by YARD this is a YARD / template issue.

Loren is helping us out with rdoc.info now (on the "team" if you will), and has some swanky new stuff he's testing out over at yardoc.com. The updated templates in use there seem to list method names alphabetically already.

The goal is to eventually integrate all of this (once any issues are ironed out) into rdoc.info.

zapnap commented 14 years ago

The latest version of rdoc.info uses YARD 0.4.0 and a customized version of the stock template. Method names should be listed alphabetically there.