api.rubyonrails.org needs to show accessors

[Matt Neuburg]

I'm just a rails newbie but I am starting to realize that a cause of my difficulties is that important methods are not listed anywhere in the docs. For example, what could be more fundamental for a beginner to know than that a controller has a `request` method through which it can learn the entire incoming ActionDispatch::Request object? This seems to be an attribute of ActionController::Metal, though I'm a bit unclear about that. But the thing is that it isn't documented anywhere that I can find. At http://api.rubyonrails.org/ I can't find any "request" that looks like this method. But these are the docs - aren't they? I could be wrong, of course, but the fact something so important is so hard to find is confusing. Am I making sense? Thx - m.

[Andreas Arnold]

They are documented in the ActionController guide: http://guides.rubyonrails.org/action_controller_overview.html#the-request-and-response-objects

On Sat, Sep 15, 2012 at 5:23 AM, Matt Neuburg <matt...@gmail.com> wrote:

I'm just a rails newbie but I am starting to realize that a cause of my difficulties is that important methods are not listed anywhere in the docs. For example, what could be more fundamental for a beginner to know than that a controller has a `request` method through which it can learn the entire incoming ActionDispatch::Request object? This seems to be an attribute of ActionController::Metal, though I'm a bit unclear about that. But the thing is that it isn't documented anywhere that I can find. At http://api.rubyonrails.org/ I can't find any "request" that looks like this method. But these are the docs - aren't they? I could be wrong, of course, but the fact something so important is so hard to find is confusing. Am I making sense? Thx - m.

--
You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
To view this discussion on the web visit https://groups.google.com/d/msg/rubyonrails-docs/-/fz-idL5-9tkJ.
To post to this group, send email to rubyonra...@googlegroups.com.
To unsubscribe from this group, send email to rubyonrails-do...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.

[Matt Neuburg]

But that's like saying they are "documented" in such-and-such a book, or just "everyone knows about this, it doesn't need to be documented in the API." What I'm suggesting is that this attitude is a problem and needs to change. The API is the docs, the ultimate list of what you can say. To omit things from it on the grounds that those things are somehow well-known in some other way is nutty. You don't have to agree with me; I'm just clarifying my view. This is what someone coming from a well-defined world such as Cocoa naturally thinks. To us, the Rails world full of cliquish secrets like this. We expect everything to be laid out, plainly enumerated, in the API listing itself.

[Daniel Beattie]

The guides and the API are designed with knowledge of each others existence.

I'm sure by now you know that Rails is opinionated. If you don't like that - tough. It works well that way, and you already know that - it's why you're here.

The guides help explain some of things you are describing as cliquy. You need to put some time in learning Rails' 'opinions' before you can start running.

I'd suggest that if you wish to continue with rails without these frustrations, then you need to read the guides before you dive into the api.

That's what they are there for - and it'll be well worth it for you!

Sent from my iPhone

To view this discussion on the web visit https://groups.google.com/d/msg/rubyonrails-docs/-/T8dYvfHNj38J.

[Andreas Arnold]

I see where the confusion comes from. The standard ApplicationController inherits from ActionController::Base, not ActionController::Metal. ActionController::Base does mention the request and response objects: http://api.rubyonrails.org/classes/ActionController/Base.html

To view this discussion on the web visit https://groups.google.com/d/msg/rubyonrails-docs/-/T8dYvfHNj38J.

[Matt Neuburg]

It mentions them in words but not in the API itself. If you go to http://api.rubyonrails.org/ and use the search field at the upper left to search for "request" the relevant method never appears. That was my original point; accessors aren't showing up. I'm suggesting that that's a flaw in the docs (or the way they are generated or whatever).

[Henrik Løvborg]

I definitely recommend reading the guides if you wish to work with rails - they're the best introduction there is.

- Henrik

To view this discussion on the web visit https://groups.google.com/d/msg/rubyonrails-docs/-/ZuMuSRuo2x0J.

[Xavier Noria]

Hi Matt,

Yes you are right this is lacking in the docs. In this case the issue is that the request accessor is defined using a Rails macro called attr_internal, and we need to tell RDoc how to handle that because by default it just cannot magically interpret the macro. I'll personally fix that.

I also believe the main page of the API is basically useless. That is a page that historically was kind of an entry point to Rails, but that is no longer the case. I'd like to rewrite it completely and replace it with kind of a table of contents per component that points you to the main classes or modules.

In particular, you'd have a link in the home page that points to the documentation of the request object.

Thanks for reporting this.