Documentation for lib (#22)

* added documentation for podium's library

* recovered Testing section of README

* added godoc reference + documentation improvements

README.md

@@ -3,8 +3,9 @@
 [![Build Status](https://travis-ci.org/topfreegames/podium.svg?branch=master)](https://travis-ci.org/topfreegames/podium)
 [![Coverage Status](https://coveralls.io/repos/github/topfreegames/podium/badge.svg?branch=master)](https://coveralls.io/github/topfreegames/podium?branch=master)
 [![Go Report Card](https://goreportcard.com/badge/github.com/topfreegames/podium)](https://goreportcard.com/report/github.com/topfreegames/podium)
-[![Docs](https://readthedocs.org/projects/podium/badge/?version=latest
-)](http://podium.readthedocs.io/en/latest/) [![](https://imagelayers.io/badge/tfgco/podium:latest.svg)](https://imagelayers.io/?images=tfgco/podium:latest 'Podium Image Layers')
+[![Docs](https://readthedocs.org/projects/podium/badge/?version=latest)](http://podium.readthedocs.io/en/latest/)
+[![GoDoc](https://godoc.org/github.com/topfreegames/podium/leaderboard?status.svg)](https://godoc.org/github.com/topfreegames/podium/leaderboard)
+[![](https://imagelayers.io/badge/tfgco/podium:latest.svg)](https://imagelayers.io/?images=tfgco/podium:latest 'Podium Image Layers')
 
 A leaderboard system written in [Go](http://golang.org/) using [Redis](http://redis.io/) database. For more info, [read the docs](http://podium.readthedocs.io/en/latest/).
 
@@ -18,7 +19,8 @@ Features
 * **Members around me** - Podium easily returns members around a specific member in the leaderboard. It will even compensate if you ask for the top member or last member to make sure you get a consistent amount of members;
 * **Batch score update** - In a single operation, send a member score to many different leaderboards or many members score to the same leaderboard. This allows easy tracking of member rankings in several leaderboards at once (global, regional, clan, etc.);
 * **Easy to deploy** - Podium comes with containers already exported to docker hub for every single of our successful builds. Just pick your choice!
-* **Leaderboards with expiration** - If a player last update is older than (timeNow - X seconds), delete it from the leaderboard
+* **Leaderboards with expiration** - If a player last update is older than (timeNow - X seconds), delete it from the leaderboard;
+* **Use as library** - You can use podium as a library as well, adding leaderboard functionality directly to your application;
 
 Installation
 ------------
@@ -30,6 +32,49 @@ Install Leaderboard using the "go get" command:
 And then run
 
     make setup
+
+Quickstart (for using as library)
+--------------------------------
+
+```
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/topfreegames/podium/leaderboard"
+)
+
+func main() {
+	leaderboards, err := leaderboard.NewClient("localhost", 1234, "", 0, 200)
+	if err != nil {
+		log.Fatalf("leaderboard.NewClient failed: %v", err)
+	}
+
+	const leaderboardID = "myleaderboardID"
+
+	//setting player scores
+	players := leaderboard.Members{
+		&leaderboard.Member{Score: 10, PublicID: "player1"},
+		&leaderboard.Member{Score: 20, PublicID: "player2"},
+	}
+
+	err = leaderboards.SetMembersScore(context.Background(), leaderboardID, players, false, "")
+	if err != nil {
+		log.Fatalf("leaderboards.SetMembersScore failed: %v", err)
+	}
+
+	//getting the leaders of the leaderboard
+	leaders, err := leaderboards.GetLeaders(context.Background(), leaderboardID, 10, 1, "desc")
+	if err != nil {
+		log.Fatalf("leaderboards.GetLeaders failed: %v", err)
+	}
+
+	for _, player := range leaders {
+		fmt.Printf("Player(id: %s, score: %d rank: %d)\n", player.PublicID, player.Score, player.Rank)
+	}
+}
+```
 
 Testing
 -------

docs/index.rst

@@ -17,4 +17,5 @@ Contents:
    hosting
    leaderboard-names
    API
+   library
    benchmark

docs/library.md

@@ -0,0 +1,236 @@
+Library
+=======
+
+For detailed information, check our [reference](https://godoc.org/github.com/topfreegames/podium/leaderboard).
+All examples below have imported the leaderboard module using:
+
+```
+import "github.com/topfreegames/podium/leaderboard"
+```
+
+## Creating the client
+
+```
+const host = "localhost"
+const port = 1234
+const password = ""
+const db = 0
+const connectionTimeout = 200
+
+leaderboards, err := leaderboard.NewClient(host, port, password, db, connectionTimeout)
+```
+
+## Creating, updating or retrieving member scores
+
+```
+const leaderboardID = "lbID"
+const playerID = "playerID"
+const score = 100
+const wantToKnowPreviousRank = false //do I want to receive also the previous rank on the user?
+const scoreTTL = "100"               //how many seconds my score will be kept on the leaderboard
+
+member, err := leaderboards.SetMemberScore(context.Background(), leaderboardID, playerID, score, wantToKnowPreviousRank, scoreTTL)
+if err != nil {
+    return err
+}
+
+playerPrinter := func(publicID string, score int64, rank int) {
+    fmt.Printf("Player(id: %s, score: %d rank: %d)\n", publicID, score, rank)
+}
+
+playerPrinter(member.PublicID, member.Score, member.Rank)
+
+const order = "desc"     //if set to asc, will treat the ranking with ascending scores (less is best)
+const includeTTL = false //if set to true, will return the member's score expiration unix timestamp
+member, err = leaderboards.GetMember(context.Background(), leaderboardID, playerID, order, includeTTL)
+if err != nil {
+    return err
+}
+
+playerPrinter(member.PublicID, member.Score, member.Rank)
+```
+
+## Setting and getting member scores in bulk
+
+```
+const leaderboardID = "lbID"
+
+players := leaderboard.Members{
+    &leaderboard.Member{Score: 1000, PublicID: "playerA"},
+    &leaderboard.Member{Score: 2000, PublicID: "playerB"},
+}
+
+err := leaderboards.SetMembersScore(context.Background(), leaderboardID, players, false, "")
+if err != nil {
+    return err
+}
+
+const order = "desc"     //if set to asc, will treat the ranking with ascending scores (less is best)
+const includeTTL = false //if set to true, will return the member's score expiration unix timestamp
+members, err := leaderboards.GetMembers(context.Background(), leaderboardID, []string{"playerA", "playerB"}, order, includeTTL)
+
+for _, member := range members {
+    fmt.Printf("Player(id: %s, score: %d rank: %d)\n", member.PublicID, member.Score, member.Rank)
+}
+```
+
+## Retrieving leaderboard leaders
+
+```
+const leaderboardID = "myleaderboardID"
+
+players := leaderboard.Members{
+    &leaderboard.Member{Score: 10, PublicID: "player1"},
+    &leaderboard.Member{Score: 20, PublicID: "player2"},
+}
+
+err = leaderboards.SetMembersScore(context.Background(), leaderboardID, players, false, "")
+if err != nil {
+    log.Fatalf("leaderboards.SetMembersScore failed: %v", err)
+}
+const pageSize = 10
+const pageIdx = 1 //starts at 1
+leaders, err := leaderboards.GetLeaders(context.Background(), leaderboardID, pageSize, pageIdx, "desc")
+if err != nil {
+    log.Fatalf("leaderboards.GetLeaders failed: %v", err)
+}
+
+for _, player := range leaders {
+    fmt.Printf("Player(id: %s, score: %d rank: %d)\n", player.PublicID, player.Score, player.Rank)
+}
+```
+
+## Incrementing player scores
+
+```
+const leaderboardID = "lbID"
+const playerID = "playerA"
+const scoreIncrement = 500
+const scoreTTL = ""
+member, err := leaderboards.IncrementMemberScore(context.Background(), leaderboardID, playerID, scoreIncrement,
+    scoreTTL)
+if err != nil {
+    return err
+}
+
+fmt.Printf("Player(id: %s, score: %d rank: %d)\n", member.PublicID, member.Score, member.Rank)
+```
+
+## Number of players on a leaderboard
+
+```
+const leaderboardID = "lbID"
+count, err := leaderboards.TotalMembers(context.Background(), leaderboardID)
+if err != nil {
+    return err
+}
+fmt.Printf("Total number of players on leaderboard %s: %d\n", leaderboardID, count)
+```
+
+## Removing players from a leaderboard
+
+```
+const leaderboardID = "lbID"
+const playerIdToRemove = "playerID"
+err := leaderboards.RemoveMember(context.Background(), leaderboardID, playerIdToRemove) //removing a single player
+if err != nil {
+    return err
+}
+
+playerIDsToRemove := make([]interface{}, 2)
+playerIDsToRemove[0] = "playerA"
+playerIDsToRemove[1] = "playerB"
+
+err = leaderboards.RemoveMembers(context.Background(), leaderboardID, playerIDsToRemove) //removing multiple players
+if err != nil {
+    return err
+}
+```
+
+## Total pages of a leaderboard
+
+```
+const leaderboardID = "lbID"
+const pageSize = 10
+pageCount, err := leaderboards.TotalPages(context.Background(), leaderboardID, pageSize)
+if err != nil {
+    return err
+}
+fmt.Printf("total pages: %d\n", pageCount)
+```
+
+## Getting players around a player
+
+```
+const leaderboardID = "lbID"
+const pageSize = 10
+const getLastIfNotFound = false //if set to true, will treat members not in ranking as being in last position
+//if set to false, will return 404 when the member is not in the ranking
+const order = "asc"
+members, err := leaderboards.GetAroundMe(context.Background(), leaderboardID, pageSize, "playerID",
+    order, getLastIfNotFound)
+if err != nil {
+    return err
+}
+for _, member := range members {
+    fmt.Printf("Player(id: %s, score: %d rank: %d)\n", member.PublicID, member.Score, member.Rank)
+}
+```
+
+## Getting players around a score
+
+```
+const leaderboardID = "lbID"
+const pageSize = 10
+const score = 1500
+const order = "desc"
+
+members, err := leaderboards.GetAroundScore(context.Background(), leaderboardID, pageSize, score, order)
+if err != nil {
+    return err
+}
+for _, member := range members {
+    fmt.Printf("Player(id: %s, score: %d rank: %d)\n", member.PublicID, member.Score, member.Rank)
+}
+```
+
+## Top percentage of a leaderboard
+
+```
+const leaderboardID = "lbID"
+const pageSize = 10
+const percent = 10
+const maxMembersToReturn = 100
+const order = "asc"
+top10, err := leaderboards.GetTopPercentage(context.Background(), leaderboardID, pageSize, percent,
+    maxMembersToReturn, order)
+if err != nil {
+    return err
+}
+for _, member := range top10 {
+    fmt.Printf("Player(id: %s, score: %d rank: %d)\n", member.PublicID, member.Score, member.Rank)
+}
+```
+
+## Getting members in a range
+
+```
+const leaderboardID = "lbID"
+const startOffset = 0
+const endOffset = 10
+const order = "asc"
+members, err := leaderboards.GetMembersByRange(context.Background(), leaderboardID, startOffset, endOffset, order)
+if err != nil {
+    return err
+}
+for _, member := range members {
+    fmt.Printf("Player(id: %s, score: %d rank: %d)\n", member.PublicID, member.Score, member.Rank)
+} 
+```
+
+## Removing a leaderboard
+
+```
+const leaderboardID = "lbID"
+err := leaderboards.RemoveLeaderboard(context.Background(), leaderboardID)
+```

docs/overview.md

@@ -1,7 +1,7 @@
 Overview
 ========
 
-What is Podium? Podium is a blazing-fast HTTP Leaderboard service. It could be used to manage any number of leaderboards of people or groups, but our aim is players in a game.
+What is Podium? Podium is a blazing-fast HTTP Leaderboard service and library. It could be used to manage any number of leaderboards of people or groups, but our aim is players in a game.
 
 Podium allows easy creation of different types of leaderboards with no set-up involved. Create seasonal, localized leaderboards just by varying their names.
 
@@ -14,6 +14,7 @@ Podium allows easy creation of different types of leaderboards with no set-up in
 * **Members around me** - Podium easily returns members around a specific member in the leaderboard. It will even compensate if you ask for the top member or last member to make sure you get a consistent amount of members;
 * **Batch score update** - In a single operation, send a member score to many different leaderboards or many members score to the same leaderboard. This allows easy tracking of member rankings in several leaderboards at once (global, regional, clan, etc.);
 * **Easy to deploy** - Podium comes with containers already exported to docker hub for every single of our successful builds. Just pick your choice!
+* **Use as library** - You can use podium as a library as well, adding leaderboard functionality directly to your application;
 
 ## Architecture