2

I have seen code such as: 

Net::HTTP::Post.new(url)

If I then use ri as follows:

$ ri Net::HTTP::Post

I get almost no documentation, and:

$ ri Net::HTTP::Post.new

results in

Nothing known about Net::HTTP::Post.new

When reading the documentation for Net::HTTP, I get the suspicion that the code should be using Net::HTTP#request_post instead. I still find the correct way to use this module confusing. Why does Net::HTTP::Post.net seem to work? Even with the Net::HTTP.request_post, I get:

undefined method `request_post' for Net::HTTP:Class.

To clarify my question, what I want is to know how to:

  • Find the best documentation for ruby.
  • Given the example provided, obtain the best way to achieve the aim (which is, to make an HTTP POST request, I'll add that I need to use provide authentication, cookie, and data in the body).
  • Make sense of what it means when the methods have been annotated with 'R' (does that mean 'read-only'? That doesn't make sense because I need to set the request body, which implies write...

As a contrast, this is equivalent documentation for Python, which I understand (being a python dev myself): http://docs.python.org/2/library/httplib.html

Arafangion
  • 11,517
  • 1
  • 40
  • 72
  • Remember that Ruby does a lot of metaprogramming. `Net::HTTP::Post` might be a reference to a class created at runtime or dynamically somehow. Its [ruby-doc page](http://ruby-doc.org/stdlib-2.0.0/libdoc/net/http/rdoc/Net/HTTP/Post.html) implies as much, I'm guessing that it's just an alias for `HTTPGenericRequest` with the HTTP method preinitialised to `"POST"` – millimoose Oct 09 '13 at 00:29
  • millimoose: I've noticed that. Are there any conventions there that will give me some idea as to how to do that? Any good documentation on using the Net::HTTP module given that ri doesn't always provide good documentation in this situation? – Arafangion Oct 09 '13 at 00:31
  • 1
    Which version of Ruby are you running? – Vidya Oct 09 '13 at 00:32
  • Vidya: Right this moment, I'm using the ancient Ruby 1.8.7, and I am aware of differences between that, 1.9, and 2.0, however the documentation question seems to apply to all of them. – Arafangion Oct 09 '13 at 00:33
  • 1
    @Arafangion I'd say try ruby-doc first, and use the documentation for the newest version when the older ones are useless. (As seems to be the case here.) 2.0 seems to have added conceptual documentation for `net/http`. – millimoose Oct 09 '13 at 00:35
  • Ruby 1.8.7 didn't have a lot of the core library docs available in ri. That has changed since then. Ruby 2.0 shows three hits for `new` in HTTPGenericRequest, HTTPRequest and Net::HTTPGenericRequest::new. – the Tin Man Oct 09 '13 at 01:46
  • possible duplicate of [Why does my Ruby 'ri' tool not return results in command prompt?](http://stackoverflow.com/questions/1575373/why-does-my-ruby-ri-tool-not-return-results-in-command-prompt) – the Tin Man Oct 09 '13 at 01:53
  • theTinMan: Thanks for the link, however I disagree with that it is a duplicate of that question unless I assume that ruby simply doesn't have good docs compared with that of Python. – Arafangion Oct 09 '13 at 01:56

1 Answers1

0

Here is the answer I will ultimately accept unless someone else has a better answer:

In order to understand Ruby's documentation, do the following, in sequential order:

  • Read the documentation for the module in the latest version of Ruby that is out there. Use ruby-doc.org, even if this version is for Ruby 2.0 and you're using Ruby 1.8, it is still likely to be significantly clearer and more complete.
  • Use google to find code examples.
  • Use irb to check if examples actually work.
  • Use ri to check if documentation for your version of ruby exists. If it exists, take a look for any insight as to what might differ in your version.
  • Use reflection/introspection in order to attempt to discover any exposed methods that may be useful.
Arafangion
  • 11,517
  • 1
  • 40
  • 72