Better docs for cattr_* and mattr_*?
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!
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
Support Staff 1 Posted by lsegal on 02 Oct, 2011 02:47 PM
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 Posted by deactivated on 02 Oct, 2011 03:05 PM
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 thec
andm
are removed from the method name? If so, what's the right way to do that? Can a handler just changestatement.method_name
? If not, does that mean one would have to swallow thecattr_*
method call, and create a new correspondingattr_*
method call that would then be picked up byAttributeHandler
?Support Staff 3 Posted by lsegal on 02 Oct, 2011 04:31 PM
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 Posted by deactivated on 02 Oct, 2011 08:31 PM
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.Support Staff 5 Posted by lsegal on 02 Oct, 2011 09:00 PM
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 Posted by deactivated on 02 Oct, 2011 09:24 PM
I had some funny results when trying to work on the ident node itself, having to do with
source
andfull_source
(changes getting overwritten in funny ways). Par for the course for hacking into a parser you didn't write yourself. =)Support Staff 7 Posted by lsegal on 03 Oct, 2011 04:31 AM
So I just installed it on the server-- you should now be able to specify the plugin in your yardopts via
--plugin rails
8 Posted by deactivated on 04 Oct, 2011 08:58 PM
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:
Support Staff 9 Posted by lsegal on 19 Oct, 2011 03:42 AM
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 Posted by deactivated on 19 Oct, 2011 11:41 AM
Yep, seems like they're working now! You can close this one up.
deactivated closed this discussion on 19 Oct, 2011 11:41 AM.