Method List Items, Duplicates, and Sort Order

[MSP-Greg]

Well, as long as we're discussing that file, I noticed with the AWS Ruby SDK, there were quite a few duplicated methods on the AWS web site.

Also, duplicate method names are grouped together, but not sorted within the group.

I wondered about sorting via:

1. Method Name
2. Class / Method Name
3. Namespace

But decided to use:

1. Method Name
2. Namespace

In the file, I changed as noted --

templates/default/fulldoc/html/setup.rb

Current

140   @items = @items.sort_by {|m| m.name.to_s }

Proposed Change(s)

140   @items.uniq! { |m| [m.name, m.namespace.title] }
141   @items = @items.sort_by {|m| [m.name.to_s.downcase, m.namespace.title] }

Line 140 checks for uniqueness, 141 changes sort order and case.

I guess I felt that a 'T' method should be sorted with the t's. I noticed it after I implemented keyboard 'jumps' for the method list...

[lsegal]

Are they duplicated methods? Or just method names? Because if it's the latter, that's pretty common for large codebases. We wouldn't want to uniq based on name alone, because you'd want access to all versions of a given name (in whatever class they exist). I assume you are not removing methods across namespaces, right?

The ordering part seems reasonable.

[MSP-Greg]

Note the uniq criteria [m.name, m.namespace.title]

IOW, namespace + method name is repeated in the Method List

See http://docs.aws.amazon.com/sdkforruby/api/ switch to the Method List, jump to the a's, note duplicates (there are a lot): Aws::S3::MultipartUpload#abort Aws::S3::ListsPartsOutput#abort_date etc.

I have not needed to get familiar with the registry side of YARD, nor have I looked to see if this is due to the AWS SDK construction of classes from json.

I just wanted fix the problem.

[lsegal]

I believe the AWS SDK uses template customizations which could affect how that renders. Can you reproduce this in a vanilla YARD environment? I've never seen an instance where methods are duplicated, since they are inherently unique (Registry.all(:method) is a unique list) when coming directly from the registry, which is how YARD grabs the methods to display.

[MSP-Greg]

I changed the AWS templates to work with the html structure of my plugin, didn't really go past that. I figured if I could (relatively) easily change the AWS SDK plugin to work with it, other plugin could be made to work with it.

Poking around, the AWS SDK file doc-src/plugins/resources.rb has six statements using

YARD::CodeObjects::MethodObject.new

but, I can't find register anywhere. Hence, as you mentioned, it seems that even though they're creating YARD objects to work with the template system, maybe they're not adding them to the registry.

BTW, sorry, I assumed you were familiar with the AWS plugin, templates, etc.

[lsegal]

Method object creation immediately registers in the registry (new is overloaded). It might be related to the way objects are displayed in the template itself rather than the select, but I'm not entirely sure. @trevorrowe manages the doc plugins for that project. If you can reproduce it in plain YARD we can confirm it as a bug here.

[MSP-Greg]

FYI, I tried to duplicate the issue with both YARD and my YARD js addon, and neither duplicated any method names. Must be on the AWS side of things.

Sorry for my not checking into it more. RE the sorting, if YARD's been that way for a while, might as well leave it. I've got the two lines in my template code...

One question. In yard-js, several of the handlers have statements similar to

obj = register YARD::CodeObjects::_SOME_OJBECT_.new(...)

So where is register defined?

TIA.

[lsegal]

So where is register defined?

register is part of YARD::Handlers::Base and is specific to handler code. It's not necessary to add to the registry, but it is useful to configure default values (like docstring data, file/line info) associated with the statement being parsed in the handler. A better name, in 5+ years of retrospect, would have been something like "build" or "configure".

[lsegal]

Just to confirm, is this a problem with vanilla YARD? If not, I think this should be marked as closed.

[MSP-Greg]

Yes, you can mark it as closed. In yard-t2, I've added <=> methods to many of the CodeObjects, so the 'Method List' will sort by name, then namespace. Probably a bit more efficient than using sort_by, which can create a lot more objects.

The duplicate issue was specific to AWS, and I never got back to it to see how that was happening. One of these days...

[lsegal]

Thanks! Closing.