From fc0c98e4d258693cfa3479d4bfe0872487b2672f Mon Sep 17 00:00:00 2001
From: Christine Dodrill <xena@yolo-swag.com>
Date: Wed, 12 Aug 2015 13:24:28 -0700
Subject: [PATCH] Add nim documentation to nim module

---
 client/nim/ponyapi.nim | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/client/nim/ponyapi.nim b/client/nim/ponyapi.nim
index 97ff1d0..fff0fb6 100644
--- a/client/nim/ponyapi.nim
+++ b/client/nim/ponyapi.nim
@@ -2,25 +2,30 @@ import cgi
 import httpclient
 import json
 
+## A bunch of glue for Nim applications to query PonyAPI.
+
 type
   Episode* = object of RootObj
-    name*: string
-    air_date*: int
-    season*: int
-    episode*: int
-    is_movie*: bool
+    ## An episode of My Little Pony: Friendship is Magic
+    name*: string   ## Episode name
+    air_date*: int  ## Air date in unix time
+    season*: int    ## season number of the episode
+    episode*: int   ## the episode number in the season
+    is_movie*: bool ## does this record represent a movie?
 
 const
   API_ENDPOINT: string = "http://ponyapi.apps.xeserv.us"
 
 proc getJson(endpoint: string): json.JsonNode =
+  ## get the HTTP body for the API base endpoint catted with the specific endpoint
+  ## requested.
   var
     data = httpclient.getContent(API_ENDPOINT & "/" & endpoint)
-    jsonTable = json.parseJson data
 
-  return jsonTable
+  data.parseJson
 
 proc newEpisodeFromNode(data: json.JsonNode): Episode =
+  ## Convert a json node into an episode object
   Episode(name:     data["name"].getStr,
           air_date: data["air_date"].getNum.int,
           season:   data["season"].getNum.int,
@@ -28,6 +33,7 @@ proc newEpisodeFromNode(data: json.JsonNode): Episode =
           is_movie: data["is_movie"].getBVal)
 
 proc newEpisodeListFromNode(data: json.JsonNode): seq[Episode] =
+  ## Convert a json array into a sequence of episode objects
   var ret: seq[Episode]
   for item in data.items():
     ret = ret & item.newEpisodeFromNode
@@ -35,21 +41,27 @@ proc newEpisodeListFromNode(data: json.JsonNode): seq[Episode] =
   return ret
 
 proc newest*(): Episode =
+  ## returns information on the newest episode of My Little Pony: Friendship is Magic.
   getJson("/newest")["episode"].newEpisodeFromNode
 
 proc random*(): Episode =
+  ## returns information on a random episode.
   getJson("/random")["episode"].newEpisodeFromNode
 
 proc get_episode*(season, episode: int): Episode =
+  ## return an arbitrary episode by season, episode pair.
   getJson("/season/" & $season & "/episode/" & $episode)["episode"].newEpisodeFromNode
 
 proc all_episodes*(): seq[Episode] =
+  ## return all information on all episodes.
   getJson("/all")["episodes"].newEpisodeListFromNode
 
 proc get_season*(season: int): seq[Episode] =
+  ## return all information on a single season.
   getJson("/season/" & $season)["episodes"].newEpisodeListFromNode
 
 proc search*(term: string): seq[Episode] =
+  ## searches for episodes by the given query term.
   getJson("/search?q=" & term.encodeURL())["episodes"].newEpisodeListFromNode
 
 when isMainModule: