search

onesky / onesky-ruby

Ruby client for OneSky Platform API
MIT License
13 stars 29 forks source link

Please provide API documentation in comments, or at least provide a reference. #8

Closed 0x1eef closed 8 years ago

0x1eef commented 8 years ago

Specifically, upload_file is not documented but it doesn't seem like any method is documented. It should be documented, or at the very least, provide a reference to the HTTP API documentation beside each method. cc @rubyluk

0x1eef commented 8 years ago

for upload_file, please reference this: https://github.com/onesky/api-documentation-platform/blob/master/resources/file.md#upload---upload-a-file

rubyluk commented 8 years ago

Resolved by https://github.com/onesky/onesky-ruby/commit/427a9fe9ef4e96cb0c7d2345a6097a0012cb27bc

0x1eef commented 8 years ago

hi @rubyluk - thank you but i do not think that is a good solution. Can you make it more clear that "Platform API" links to documentation ? it is very unclear, and in any case, it does not provide a reference from API documentation. onesky-ruby gem is totally useless inside pry and when using its show-doc command, as well for example. It is not good practice to leave any gem 100% undocumented. I recommend you consider something like http://yardoc.org/ to provide accurate and informative documentation, it supports tags, so you could use @see tag to reference that markdown document.

i'm disappointed by the solution. "OneSky"(active link) "Platform API"(active link). these are two different links going to two different places, they are present in README only, and yeah... very poor, i'm sad to say.

0x1eef commented 8 years ago

that i even have to explain this, it worries me very much. i can't really believe it in a way.

0x1eef commented 8 years ago

the code itself by the way, has so much indirection going on(very bad for code nav), that finding "upload_file" definition was hard work and when i do find it, it's undocumented, and i have to go back to the readme to somehow notice that second link which is not a direct link to the HTTP API docs for upload_file, it requires more jumps to get there. please provide a better solution.