Doorkeeper: Improve API documentation

Created on 3 Jul 2016 · 12Comments · Source: doorkeeper-gem/doorkeeper

I'm finding it extremely difficult to learn how to use Doorkeeper, especially since the most common use cases seem to be not mine. In particular, API documentation would be critical. There are some examples and tutorials, but they aren't exhaustive. In fact, I find myself going through Doorkeeper's code many times over to check whether certain methods exist, what their names are, what parameters they might accept, and so on.

I know this sounds like something I should be taking up myself, but as I said, I'm trying to navigate it, with limited success…

docs help wanted

Source

Morpheu5

All 12 comments

@Morpheu5, thanks for your comment. I agree that documentation is very lacking for this project. I won't have the time to work on this, but will leave this issue open, and retitle it to better describe the problem, welcoming contributors who might help.
Thanks!

tute on 7 Jul 2016

@Morpheu5 - do you have a specific issue/question you would like documented or covered better? I just went thru the process of using Doorkeeper to setup an OAuth provider with an existing rails application. If you post a specific issue/question, then perhaps I (or others) can take a crack at it and improve the docs for everyone's benefit.

treble37 on 26 Aug 2016

@Morpheu5 what would be actionable steps to move this issue forward? Is there another rubygem for which we can follow the example and improve our API documentation? Is there another software package (not necessarily a gem) you have in mind?
Thanks!

tute on 31 Aug 2016

Hey - sorry for the delay.

@treble37 I couldn't find clear docs on setting up authentication using the password grant, for example, so I had to read the OAuth2 specification and proceed by trial and error with doorkeeper. I think I got it to work, but I'm not sure I got it to work correctly :) There are a lot of such holes in the docs. To answer @tute's question too, API level documentation is nearly non-existent — I mean documenting which methods do what, what parameters they expect, and so on. It's really guesswork at this point, working backwards from the examples and the RFC. Then, a higher level set of docs on how to implement and use the different grants, and so on, that would be useful too. I would start with completing the API's docs first, that will eliminate a lot of guesswork.

Morpheu5 on 31 Aug 2016

For the API level docs, is this sample (from grape) what you would consider good documentation for the API @Morpheu5 (basically adding comments / descriptions within the code)?

treble37 on 1 Sep 2016

👍1

@treble37 Yes, that is an excellent example. In the past, I used apipie, and more recently swagger-ui. Apipie can generate html docs that you can host separately, if need be. Integrating with Read The Docs might be overkill, but an interesting long-term goal.

Morpheu5 on 1 Sep 2016

@Morpheu5 - https://github.com/doorkeeper-gem/doorkeeper/pull/881/files - what do you think so far? I started on something small to illustrate a possible approach.

@tute - any thoughts and/or preference on a documentation format (e.g., should we use RDoc or Yard)? It looks like you might prefer RDoc, but maybe we should clarify before proceeding further? Yard is a superset of RDoc from what I understand.

treble37 on 17 Sep 2016

@Morpheu5 - https://github.com/doorkeeper-gem/doorkeeper/pull/881/files - what do you think so far? I started on something small to illustrate a possible approach.

This makes me very happy. Thank you!

@tute - any thoughts and/or preference on a documentation format (e.g., should we use RDoc or Yard)? It looks like you might prefer RDoc, but maybe we should clarify before proceeding further? Yard is a superset of RDoc from what I understand.

I'd go with Yard. Thanks!

tute on 19 Sep 2016

👍1

@Morpheu5 - https://github.com/doorkeeper-gem/doorkeeper/pull/881/files - what do you think so far? I started on something small to illustrate a possible approach.

That's a very good start! If I may, I'd rather have one-liners to explain what a method does (if one line is sufficient) and then a detailed list of parameters and values and so on (see that example from grape). Anyway, that's a good start, thank you!

Morpheu5 on 20 Sep 2016

👍1

@Morpheu5 - so I updated the PR with the latest Yard format and your suggestions....what do you think? Seems like we're pretty close and once we're all in fair agreement, I'll go ahead and make other PRs to update the docs following an agreed upon convention.

treble37 on 23 Sep 2016

@treble37 that makes me so happy! :) I left a comment in the diff https://github.com/doorkeeper-gem/doorkeeper/pull/881/files#r80362862 but apart from that, it looks like you are on the right track!

Morpheu5 on 24 Sep 2016

Doorkeeper configuration & models now have YARD docs. Also there are great Wiki articles and many StackOverflow / Blog posts around to share the ideas of how to use it.

I don't think that lack of full docs coverage is the real "issue", so I will close it. Anyway everybody are welcome to send a PR with docs improvements ❤️