api.rubyonrails.org needs to show accessors

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.

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

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.

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!

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

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).

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

  • Henrik

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.