hexgnu/linkedin — pull request #204 by hundredwatt (2014-01-18 17:32:42+00:00)
Title: Documentation

This is for https://github.com/hexgnu/linkedin/issues/192

I switched from rdoc to yard as the documentation engine. I then went through and documented all the API methods and other classes. Finally, I re-organized the API module into submodules based on how LinkedIn organizes the APIs in their documentation. I also made a number of small changes and additions to help clean up and complete the documentation.

Further, I went through all the LinkedIn REST API documentation and added a note at the top of each submodule with any endpoints that are missing from this library.

--

This is not quite ready to be merged, but its very close, so I figured I'd go ahead and open a PR to start the discussion. Here are the remaining questions I had:

1. Hyphenated Query Parameters
The LinkedIn API uses hyphenated names for multi-word parameters. The Ruby convention is to use underscores in symbol names, so that's what I did in the documentation. Will the Client automatically convert underscore to hyphenated when the requests are made or should I go back and change the documentation to hyphenated names?

Example: "event-type" for company updates.
Here: https://github.com/hundredwatt/linkedin/blob/docs/lib/linked_in/api/companies.rb#L39
vs
Here: http://developer.linkedin.com/reading-company-shares

2. `x-li-auth-token` Header
The `x-li-auth-token` header is used to access out of network profiles: http://developer.linkedin.com/documents/accessing-out-network-profiles

It doesn't look like its currently possible to add this header to a #profile request, is that correct?
Assuming so, I wanted to get thoughts on address this in documentation and modifying the code to allow setting this header? Or perhaps this is something that should wait for #187 and switching to Faraday?

--

A couple other nice to haves. Should I open these as separate issues?

1. Instead of having the #search method take a type and live in the Search module, I think it should be split into 3 separate methods and then place them in the appropriate modules: #people_search, #company_search, #job_search

2. For #send_message in the Communications API, should we use the person_path helper instead of asking the user to supply an array of person_paths? https://github.com/hundredwatt/linkedin/blob/docs/lib/linked_in/api/communications.rb#L34. I haven't personally used the Communications API, so I'm not sure what's best here.

--

Let me know if there are any questions/comments/feedback on any of the commits in my docs branch