Better docs for cattr_* and mattr_*?

deactivated's Avatar

deactivated

02 Oct, 2011 02:17 PM

Right now, cattr_* methods show up as instance methods (see the facets and num_results methods here for an example). It'd be great if RubyDoc installed a really simple handler for these accessors -- even the one listed in the YARD docs on handler-writing puts these into a really nice "Class Attributes" section:

class ClassAttributeHandler < YARD::Handlers::Ruby::AttributeHandler
  handles method_call(:cattr_accessor)
  handles method_call(:cattr_reader)
  handles method_call(:cattr_writer)
  handles method_call(:mattr_accessor)
  handles method_call(:mattr_reader)
  handles method_call(:mattr_writer)
  namespace_only

  def process
    push_state(:scope => :class) { super }
  end
end

I believe, from reading the code, that that handler will currently make all those accessors appear read-only, but it's better than the current formatting that's now available on RubyDoc. If I knew a bit more about YARD internals, all that I think needs to be done to that handler to make it perfect is to shave the c or m off the front of the statement method name before passing up to super.

In any event, some nicer formatting for class and method attributes would be really great, since I know there's a lot of Rails projects documented here on RubyDoc. Thanks for a great service!

  1. Support Staff 1 Posted by lsegal on 02 Oct, 2011 02:47 PM

    lsegal's Avatar

    If you packaged this up as a plugin and put the gem up on rubygems.org we could install this on rubydoc.info and everybody would win! Interested? :)

    And yes, that handler looks like it would work just fine as is. Of course any improvements could be made over time (release early / often!), but it's a fine start.

  2. 2 Posted by deactivated on 02 Oct, 2011 03:05 PM

    deactivated's Avatar

    Let me see what I can do -- never released a gem before! But you're right, this seems like a good time to give it a shot.

    Am I right in reading the AttributeHandler code that the read/write detection there won't work unless the c and m are removed from the method name? If so, what's the right way to do that? Can a handler just change statement.method_name? If not, does that mean one would have to swallow the cattr_* method call, and create a new corresponding attr_* method call that would then be picked up by AttributeHandler?

  3. Support Staff 3 Posted by lsegal on 02 Oct, 2011 04:31 PM

    lsegal's Avatar

    Yes, you are correct that you would need to change the names. You CAN forcibly rewrite the AST node (it's just an array object, effectively), and this would probably be a reasonable hack until we found a better way to do this. We should probably refactor the attr handler to not hardcode those read write attribute method names, that would be the best. Until then, you can rewrite the method name and call super. The other way to do it would be to manually set the object as writable after the object is created, but that's probably uglier.

  4. 4 Posted by deactivated on 02 Oct, 2011 08:31 PM

    deactivated's Avatar

    This whole gem thing isn't as hard as I expected. https://rubygems.org/gems/yard-rails It comes with a small RSpec test suite, which currently only tests [c,m]attr_* on both the 1.9 and the legacy 1.8 parser.

    1.9-parser source is here, and 1.8-parser source is here. In both cases, I just clobber statement[0] and replace it with the appropriate new AST node/token text, which seems to work like a champ for now.

  5. Support Staff 5 Posted by lsegal on 02 Oct, 2011 09:00 PM

    lsegal's Avatar

    Awesome! Will get it installed soon. Just as a side note, have you tried just doing a string mutation directly on the method name object itself? Like .replace, or just replace the name element in the ident node. Those would save you from recreating the node from scratch, but I guess golfing a hack is kind of pointless...

  6. 6 Posted by deactivated on 02 Oct, 2011 09:24 PM

    deactivated's Avatar

    I had some funny results when trying to work on the ident node itself, having to do with source and full_source (changes getting overwritten in funny ways). Par for the course for hacking into a parser you didn't write yourself. =)

  7. Support Staff 7 Posted by lsegal on 03 Oct, 2011 04:31 AM

    lsegal's Avatar

    So I just installed it on the server-- you should now be able to specify the plugin in your yardopts via --plugin rails

  8. 8 Posted by deactivated on 04 Oct, 2011 08:58 PM

    deactivated's Avatar

    I think I set this up right (yardopts file is here), but I'm not seeing the updated docs. See the docs for the Document class here. When I run YARD locally with the plugin installed, I get the following section, which is still absent on Rubydoc:

    Class Attribute Summary
    + (Hash) facets readonly
    Faceted browsing information that was returned by the last search.
    + (Integer) num_results readonly
    Number of documents returned by the last search.

  9. Support Staff 9 Posted by lsegal on 19 Oct, 2011 03:42 AM

    lsegal's Avatar

    Hey sorry for the late reply. Did you manage to get this working? I'm seeing those class attributes showing up now. But it might have been something I did on the server.

  10. 10 Posted by deactivated on 19 Oct, 2011 11:41 AM

    deactivated's Avatar

    Yep, seems like they're working now! You can close this one up.

  11. deactivated closed this discussion on 19 Oct, 2011 11:41 AM.

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts

Generic

? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac