github: enhance Github documentation as example for Nitdoc README files

Signed-off-by: Alexandre Terrasa <alexandre@moz-code.org>

diff --git a/lib/github/README.md b/lib/github/README.md
new file mode 100644 (file)
index 0000000..64a7e98
--- /dev/null
+++ b/lib/github/README.md
@@ -0,0 +1,71 @@
+# Nit wrapper for Github API
+
+This module provides a Nit object oriented interface to access the Github api.
+
+## Accessing the API
+
+[[doc: GithubAPI]]
+
+### Authentification
+
+[[doc: GithubAPI::auth]]
+
+Token can also be recovered from user config with `get_github_oauth`.
+
+[[doc: get_github_oauth]]
+
+### Retrieving user data
+
+[[doc: load_user]]
+[[doc: User]]
+[[list: User]]
+
+### Retrieving repo data
+
+[[doc: load_repo]]
+[[doc: Repo]]
+[[list: Repo]]
+
+### Other data
+
+[[list: api]]
+
+### Advanced uses
+
+#### Caching
+
+[[doc: cache]]
+
+#### Custom requests
+
+[[doc: GithubAPI::get]]
+
+#### Change the user agent
+
+[[doc: GithubAPI::user_agent]]
+
+#### Debugging
+
+[[doc: verbose_lvl]]
+
+#### Using with GitLab
+
+If URL scheme of GitLab API follows the one of Github API, it may be possible to
+configure this wrapper to use a custom URL.
+
+[[doc: api_url]]
+
+## Creating hooks
+
+Using this API you can create Github hooks able to respond to actions performed
+on a repository.
+
+[[doc: hooks]]
+
+## Dealing with events
+
+GithubAPI can trigger different events depending on the hook configuration.
+
+[[doc: GithubEvent]]
+
+[[list: github::events]]

diff --git a/lib/github/api.nit b/lib/github/api.nit
index 6f7c7d9..0d5a67a 100644 (file)
--- a/lib/github/api.nit
+++ b/lib/github/api.nit
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Nit object oriented interface to Github api.
+# Nit object oriented interface to [Github api](https://developer.github.com/v3/).
 #
 # This modules reifies Github API elements as Nit classes.
 #
@@ -21,11 +21,9 @@ module api
 
 import github_curl
 
-# Interface to Github REST API.
+# Client to Github API
 #
-# Used by all `GithubEntity` to perform requests.
-#
-# Usage:
+# To access the API you need an instance of a `GithubAPI` client.
 #
 # ~~~
 # # Get Github authentification token.
@@ -36,7 +34,7 @@ import github_curl
 # var api = new GithubAPI(token)
 # ~~~
 #
-# The API client allows to get Github API entities:
+# The API client allows you to get Github API entities.
 #
 # ~~~
 # var repo = api.load_repo("privat/nit")
@@ -49,9 +47,16 @@ import github_curl
 # ~~~
 class GithubAPI
 
-       # Github API OAuth token.
+       # Github API OAuth token
+       #
+       # To access your private ressources, you must
+       # [authenticate](https://developer.github.com/guides/basics-of-authentication/).
+       #
+       # For client applications, Github recommands to use the
+       # [OAuth tokens](https://developer.github.com/v3/oauth/) authentification method.
+       #
+       #
        #
-       # This token is used to authenticate the application on Github API.
        # Be aware that there is [rate limits](https://developer.github.com/v3/rate_limit/)
        # associated to the key.
        var auth: String
@@ -140,9 +145,9 @@ class GithubAPI
                return res.as(JsonObject)
        end
 
-       # Get the Github user with `login`.
+       # Get the Github user with `login`
        #
-       # Returns `null` if the user cannot be found.
+       # Loads the `User` from the API or returns `null` if the user cannot be found.
        #
        #     var api = new GithubAPI(get_github_oauth)
        #     var user = api.load_user("Morriar")
@@ -154,7 +159,7 @@ class GithubAPI
 
        # Get the Github repo with `full_name`.
        #
-       # Returns `null` if the repo cannot be found.
+       # Loads the `Repo` from the API or returns `null` if the repo cannot be found.
        #
        #     var api = new GithubAPI(get_github_oauth)
        #     var repo = api.load_repo("privat/nit")
@@ -349,11 +354,10 @@ abstract class GithubEntity
        fun html_url: String do return json["html_url"].to_s
 end
 
-# A Github user.
+# A Github user
 #
+# Provides access to [Github user data](https://developer.github.com/v3/users/).
 # Should be accessed from `GithubAPI::load_user`.
-#
-# See <https://developer.github.com/v3/users/>.
 class User
        super GithubEntity
 
@@ -374,9 +378,8 @@ end
 
 # A Github repository.
 #
+# Provides access to [Github repo data](https://developer.github.com/v3/repos/).
 # Should be accessed from `GithubAPI::load_repo`.
-#
-# See <https://developer.github.com/v3/repos/>.
 class Repo
        super GithubEntity
 

diff --git a/lib/github/github.nit b/lib/github/github.nit
index 9bc63a8..d4d5904 100644 (file)
--- a/lib/github/github.nit
+++ b/lib/github/github.nit
@@ -12,7 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Github API related features.
+# Nit wrapper for Github API
+#
+# This module provides a Nit object oriented interface to access the
+# [Github api](https://developer.github.com/v3/).
 module github
 
 import cache

diff --git a/lib/github/github_curl.nit b/lib/github/github_curl.nit
index 62776e6..dea87e4 100644 (file)
--- a/lib/github/github_curl.nit
+++ b/lib/github/github_curl.nit
@@ -131,8 +131,10 @@ class GithubError
        redef fun to_s do return "[{name}] {super}"
 end
 
+# Gets the Github token from `git` configuration
+#
 # Return the value of `git config --get github.oauthtoken`
-# return "" if no such a key
+# or `""` if no key exists.
 fun get_github_oauth: String
 do
        var p = new ProcessReader("git", "config", "--get", "github.oauthtoken")