Skip to content

Commit 45a07d9

Browse files
thecswthecsw
committed
Added more documentation
Signed-off-by: Sandy House <ctu@ku.edu>
1 parent 78c525a commit 45a07d9

9 files changed

+119
-366
lines changed

‎auth.go

+3-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ type Credentials struct {
1818
UserAgent string
1919
}
2020

21-
// Returns an access_token acquired using the provided credentials
21+
// Authenticate returns *Reddit object that has been authed
2222
func Authenticate(c *Credentials) (*Reddit, error) {
2323
// URL to get access_token
2424
auth_url := RedditBase + "api/v1/access_token"
@@ -84,6 +84,7 @@ func (c *Reddit) update_creds() {
8484
c.Token = temp.Token
8585
}
8686

87+
// SetDefault sets all default values
8788
func (c *Reddit) SetDefault() {
8889
c.Stream = Streaming{
8990
CommentListInterval: 8,
@@ -95,6 +96,7 @@ func (c *Reddit) SetDefault() {
9596
}
9697
}
9798

99+
// SetClient sets mira's *http.Client to make requests
98100
func (c *Reddit) SetClient(client *http.Client) {
99101
c.Client = client
100102
}

‎const.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
package mira
22

3-
// Base is the basic reddit base URL, authed is the base URL for use once authenticated
4-
53
const (
6-
RedditBase = "https://www.reddit.com/"
4+
// RedditBase is the basic reddit base URL, authed is the base URL for use once authenticated
5+
RedditBase = "https://www.reddit.com/"
6+
// RedditOauth is the oauth url to pass the tokens to
77
RedditOauth = "https://oauth.reddit.com"
88
)

‎doc.go

+5-290
Original file line numberDiff line numberDiff line change
@@ -1,291 +1,6 @@
1-
// # MIRA or Meme Investor Reddit Api
2-
3-
// [![Go Report Card](https://goreportcard.com/badge/github.com/thecsw/mira)](https://goreportcard.com/report/github.com/thecsw/mira)
4-
// [![Build Status](https://travis-ci.org/thecsw/mira.svg?branch=master)](https://travis-ci.org/thecsw/mira)
5-
// [![GoDoc](https://godoc.org/github.com/thecsw/mira?status.svg)](https://godoc.org/github.com/thecsw/mira)
6-
// [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
7-
8-
// For full documentation, please see the [Godoc page](https://godoc.org/github.com/thecsw/mira)
9-
10-
// MIRA is a Reddit Api Wrapper written in beautiful Go. This is a subproject
11-
// of a bigger project MemeInvestor_bot.
12-
13-
// It is super simple to use the bot as we also provide you
14-
// with simple but fully extensive structs. We utilize the
15-
// best features of Go, such as closures, channels, goroutines, garbage collection, etc.
16-
17-
// Currently, `mira` is a project that just began its life. We still have many new Reddit
18-
// endpoints to cover. We have the basic functionality implemented, like streaming comment
19-
// replies, new submissions. Comment, post, edit, reply, and delete options for our
20-
// instances.
21-
22-
// Two quick notes: all actions should be done via `Reddit` struct, I thought it would make it
23-
// simpler to work with. Secondly, all actions require the objects full `thing_id`, so you have
24-
// to use `GetId()` to get that id. Every struct has that method implemented and it will return
25-
// a string in the form of `t[1-6]_[a-z0-9]{5}`. Refer to the following table for the classifications
26-
// of the structs.
27-
28-
// **Type Prefixes**
29-
30-
// | Prefix | Type |
31-
// |--------|----------------------------------|
32-
// | t1 | Comment |
33-
// | t2 | Redditor |
34-
// | t3 | Submission, PostListing contents |
35-
// | t4 | Message (NOT IMPLEMENTED) |
36-
// | t5 | Subreddit |
37-
// | t6 | Award (NOT IMPLEMENTED) |
38-
39-
// ## Config file
40-
41-
// The config file structure is very simple:
42-
43-
// ```
44-
// CLIENT_ID =
45-
// CLIENT_SECRET =
46-
// USERNAME =
47-
// PASSWORD =
48-
// USER_AGENT =
49-
// ```
50-
51-
// ## Environment setup
52-
53-
// Mira also works with environmental variables, here is an example from docker-compose
54-
55-
// ```
56-
// environment:
57-
// - BOT_CLIENT_ID=hunteoahtnhnt432
58-
// - BOT_CLIENT_SECRET=ehoantehont4ht34hnt332
59-
// - BOT_USER_AGENT='u/mytestbot developed by thecsw'
60-
// - BOT_USERNAME=mytestbot
61-
// - BOT_PASSWORD=verygoodpassword
62-
// ```
63-
64-
// And the login will look like this:
65-
66-
// ``` go
67-
// r, err := mira.Init(mira.ReadCredsFromEnv())
68-
// ```
69-
70-
// Or you can always just fill in the values directly.
71-
72-
// ## Examples
73-
74-
// Note: Error checking is omitted for brevity.
75-
76-
// ### Streaming
77-
78-
// Streaming new submissions is very simple! *mira* supports streaming comment replies,
79-
// mentions, new subreddit's/redditor's comments, and new subreddit's/redditor's submissions.
80-
81-
// ``` go
82-
// // r is an instance of *mira.Reddit
83-
84-
// // Start streaming my comment replies
85-
// c, _ := r.StreamCommentReplies()
86-
// for {
87-
// msg := <-c
88-
// r.Comment(msg.GetId()).Reply("I got your message!")
89-
// }
90-
91-
// // Start streaming my mentions
92-
// // Start streaming my comment replies
93-
// c, _ := r.StreamMentions()
94-
// for {
95-
// msg := <-c
96-
// r.Comment(msg.GetId()).Reply("I got your mention of me!")
97-
// }
98-
99-
// // Start streaming subreddits' submissions
100-
// c, _, _ := r.Subreddit("tifu", "wholesomememes").StreamSubmissions()
101-
// for {
102-
// post := <-c
103-
// r.Submission(post.GetId()).Save("hello there")
104-
// }
105-
106-
// // NOTE: Second value is the stop channel. Send a true value
107-
// // to the stop channel and the goroutine will return.
108-
// // Basically, `stop <- true`
109-
110-
// // Start streaming subreddits' comments
111-
// c, _, _ := r.Subreddit("all").StreamComments()
112-
// for {
113-
// msg := <-c
114-
// r.Comment(msg.GetId()).Reply("my reply!")
115-
// }
116-
117-
// // Start streaming redditor's submissions
118-
// c, _, _ := r.Redditor("thecsw").StreamSubmissions()
119-
// for {
120-
// post := <-c
121-
// r.Submission(post.GetId()).Save("hello there")
122-
// }
123-
124-
// // Start streaming redditor' comments
125-
// c, _, _ := r.Redditor("thecsw").StreamComments()
126-
// for {
127-
// msg := <-c
128-
// r.Comment(msg.GetId()).Reply("my reply!")
129-
// }
130-
// ```
131-
132-
// ### Submitting, Commenting, Replying, and Editing
133-
134-
// It is very easy to post a submission, comment on it, reply to a message, or
135-
// edit a comment.
136-
137-
// ``` go
138-
// package main
139-
140-
// import (
141-
// "fmt"
142-
143-
// "github.com/thecsw/mira"
144-
// )
145-
146-
// // Errors are omitted for brevity
147-
// func main() {
148-
// r, _ := mira.Init(mira.ReadCredsFromFile("login.conf"))
149-
150-
// // Make a submission
151-
// post, _ := r.Subreddit("mysubreddit").Submit("mytitle", "mytext")
152-
153-
// // Comment on our new submission
154-
// comment, _ := r.Submission(post.GetId()).Save("mycomment")
155-
156-
// // Reply to our own comment
157-
// reply, _ := r.Comment(comment.GetId()).Reply("myreply")
158-
159-
// // Delete the reply
160-
// r.Comment(reply.GetId()).Delete()
161-
162-
// // Edit the first comment
163-
// newComment, _ := r.Comment(comment.GetId()).Edit("myedit")
164-
165-
// // Show the comment's body
166-
// fmt.Println(newComment.GetBody())
167-
// }
168-
// ```
169-
170-
// ### Composing a message
171-
172-
// We can also send a message to another user!
173-
174-
// ``` go
175-
// package main
176-
177-
// import (
178-
// "github.com/thecsw/mira"
179-
// )
180-
181-
// func main() {
182-
// r, _ := mira.Init(mira.ReadCredsFromFile("login.conf"))
183-
184-
// r.Redditor("myuser").Compose("mytitle", "mytext")
185-
// }
186-
// ```
187-
188-
// ### Going through hot, new, top, rising, controversial, and random
189-
190-
// You can also traverse through a number of submissions using
191-
// one of our methods.
192-
193-
// ``` go
194-
// package main
195-
196-
// import (
197-
// "fmt"
198-
199-
// "github.com/thecsw/mira"
200-
// )
201-
202-
// func main() {
203-
// r, _ := mira.Init(mira.ReadCredsFromFile("login.conf"))
204-
// sort := "top"
205-
// var limit int = 25
206-
// duration := "all"
207-
// subs, _ := r.Subreddit("all").Submissions(sort, duration, limit)
208-
// for _, v := range subs {
209-
// fmt.Println("Submission Title: ", v.GetTitle())
210-
// }
211-
// }
212-
// ```
213-
214-
// ### Getting reddit info
215-
216-
// You can extract info from any reddit ID using mira. The returned value is an
217-
// instance of mira.MiraInterface.
218-
219-
// ``` go
220-
// package main
221-
222-
// import (
223-
// "fmt"
224-
225-
// "github.com/thecsw/mira"
226-
// )
227-
228-
// func main() {
229-
// r, _ := mira.Init(mira.ReadCredsFromFile("login.conf"))
230-
// me, _ := r.Me().Info()
231-
// comment, _ := r.Comment("t1_...").Info()
232-
// redditor, _ := r.Redditor.Info("t2_...")
233-
// submission, _ := r.Submission("t3_...").Info()
234-
// subreddit, _ := r.Subreddit("t5_...").Info()
235-
// }
236-
// ```
237-
238-
// Here is the interface:
239-
240-
// ``` go
241-
// type MiraInterface interface {
242-
// GetId() string
243-
// GetParentId() string
244-
// GetTitle() string
245-
// GetBody() string
246-
// GetAuthor() string
247-
// GetName() string
248-
// GetKarma() float64
249-
// GetUps() float64
250-
// GetDowns() float64
251-
// GetSubreddit() string
252-
// GetCreated() float64
253-
// GetFlair() string
254-
// GetUrl() string
255-
// IsRoot() bool
256-
// }
257-
// ```
258-
259-
// ## Mira Caller
260-
261-
// Surely, Reddit API is always developing and I can't implement all endpoints. It will be a bit of a bloat.
262-
// Instead, you have accessto *Reddit.MiraRequest method that will let you to do any custom reddit api calls!
263-
264-
// Here is the signature:
265-
266-
// ``` go
267-
// func (c *Reddit) MiraRequest(method string, target string, payload map[string]string) ([]byte, error) {...}
268-
// ```
269-
270-
// It is pretty straight-forward. The return is a slice of bytes. Parse it yourself.
271-
272-
// Here is an example of how Reddit.Reply() uses MiraRequest:
273-
274-
// ``` go
275-
// func (c *Reddit) Reply(text string) (models.CommentWrap, error) {
276-
// ret := &models.CommentWrap{}
277-
// name, _, err := c.checkType("comment")
278-
// if err != nil {
279-
// return *ret, err
280-
// }
281-
// target := RedditOauth + "/api/comment"
282-
// ans, err := c.MiraRequest("POST", target, map[string]string{
283-
// "text": text,
284-
// "thing_id": name,
285-
// "api_type": "json",
286-
// })
287-
// json.Unmarshal(ans, ret)
288-
// return *ret, err
289-
// }
290-
// ```
1+
// mira
2+
//
3+
// README at https://github.com/thecsw/mira
4+
//
5+
// All function docs here
2916
package mira

‎mira.go

+2-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@ package mira
22

33
import "net/http"
44

5-
// When we initialize the Reddit instance,
5+
// Init is used
6+
// when we initialize the Reddit instance,
67
// automatically start a goroutine that will
78
// update the token every 45 minutes. The
89
// auto_refresh should not be accessible to

0 commit comments

Comments
 (0)