tweaks to docs (#200)

.github/workflows/integration.yml

@@ -7,10 +7,10 @@ jobs:
     name: Integration tests
     runs-on: ubuntu-latest
     steps:
-    - name: Set up Go 1.13
+    - name: Set up Go 1.15
       uses: actions/setup-go@v2
       with:
-        go-version: 1.13
+        go-version: 1.15
       id: go
 
     - name: Install Protoc

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Set up Go 1.13
         uses: actions/setup-go@v1
         with:
-          go-version: 1.13
+          go-version: 1.15
         id: go
 
       - name: Check out code into the Go module directory

answer/proto/answer.proto

@@ -8,7 +8,7 @@ service Answer {
 	rpc Question(QuestionRequest) returns (QuestionResponse) {}
 }
 
-// Answer a question and receive an instant answer
+// Ask a question and receive an instant answer
 message QuestionRequest {
 	// the question to answer
 	string query = 1;

cache/README.md

@@ -2,6 +2,6 @@ Quick access key-value storage
 
 # Cache Service
 
-The cache service provides simple get/set/delete key-value storage along with ttl support.
+The cache service provides simple get/set/delete key-value storage. Values can be stored with an optional time-to-live (TTL) to automatically expire entries.
 
-The max value size is 1mb
+The max value size is 1MB.

cache/proto/cache.proto

@@ -53,32 +53,32 @@ message DeleteResponse {
 	string status = 1;
 }
 
-// Increment a value (if its a number)
+// Increment a value (if it's a number)
 message IncrementRequest {
 	// The key to increment
 	string key = 1;
-	// The value to add
+	// The amount to increment the value by
 	int64 value = 2;
 }
 
 message IncrementResponse {
 	// The key incremented
 	string key = 1;
-	// The result value
+	// The new value
 	int64 value = 2;
 }
 
-// Decrement a value (if its a number)
+// Decrement a value (if it's a number)
 message DecrementRequest {
 	// The key to decrement
 	string key = 1;
-	// The delta value to decrement
+	// The amount to decrement the value by
 	int64 value = 2;
 }
 
 message DecrementResponse {
-	// The key of the item
+	// The key decremented
 	string key = 1;
-	// The result value of the item
+	// The new value
 	int64 value = 2;
 }

crypto/README.md

@@ -1,7 +1,7 @@
-Cryptocurrency prices, quotes and news
+Cryptocurrency prices, quotes, and news
 
 # Crypto Service
 
-Get up to the second cryptocurrency prices, quotes, previous close information and news.
+Get up to the second cryptocurrency prices, quotes, previous close information, and news.
 
 Powered by [Finage](https://finage.co.uk)

crypto/proto/crypto.proto

@@ -39,7 +39,7 @@ message NewsResponse {
 
 // Get the last price for a given crypto ticker
 message PriceRequest {
-	// crypto symbol e.g BTCUSD
+	// the crypto symbol e.g BTCUSD
 	string symbol = 1;
 }
 
@@ -50,7 +50,7 @@ message PriceResponse {
 	double price = 2;
 }
 
-// Get the last quote for the crypto
+// Get the last quote for a given crypto ticker
 message QuoteRequest {
 	// the crypto symbol e.g BTCUSD
 	string symbol = 1;

db/README.md

@@ -2,4 +2,4 @@ Simple database service
 
 # DB Service
 
-The DB service is a simple database which provides persistent storage via a CRUD API. It includes fast querying, ordering and more.
+The DB service is a simple database which provides persistent storage via a Create Read Update Delete (CRUD) API. It includes fast querying, ordering, and more.

db/proto/db.proto

@@ -16,7 +16,7 @@ service Db {
 
 // Read data from a table. Lookup can be by ID or via querying any field in the record.
 message ReadRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 	// Read by id. Equivalent to 'id == "your-id"'
 	string id = 2;
@@ -27,7 +27,7 @@ message ReadRequest {
 	// Accessing list elements is not supported yet.
 	string query = 3;
 	int32 offset = 4;
-	// Default limit is 25.
+	// Maximum number of records to return. Default limit is 25.
 	// Maximum limit is 1000. Anything higher will return an error.
 	int32 limit = 5;
 	// field name to order by
@@ -41,9 +41,9 @@ message ReadResponse {
 	repeated google.protobuf.Struct records = 1;
 }
 
-// Create a record in the database. Optionally include an "id" field otherwise its set automatically.
+// Create a record in the database. Optionally include an "id" field otherwise it's set automatically.
 message CreateRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 	// JSON encoded record or records (can be array or object)
 	google.protobuf.Struct record = 2;
@@ -56,9 +56,9 @@ message CreateResponse {
 
 // Update a record in the database. Include an "id" in the record to update.
 message UpdateRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
-	// The id of the record
+	// The id of the record. If not specified it is inferred from the 'id' field of the record
 	string id = 2;
 	// record, JSON object
 	google.protobuf.Struct record = 3;
@@ -68,7 +68,7 @@ message UpdateResponse {}
 
 // Delete a record in the database by id.
 message DeleteRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 	// id of the record
 	string id = 2;
@@ -80,7 +80,7 @@ message DeleteResponse {
 
 // Truncate the records in a table
 message TruncateRequest {
-	// Optional table name
+	// Optional table name. Defaults to 'default'
 	string table = 1;
 }
 

email/README.md

@@ -2,7 +2,7 @@ Send emails in a flash
 
 # Emails Service
 
-A quick and easy email api. Simply provide a from, to and text or html body.
+A quick and easy email API. Simply provide a from, to, and text or html body.
 
 Powered by [Sendgrid](https://sendgrid.com)
 

email/proto/email.proto

@@ -8,9 +8,9 @@ service Email {
 	rpc Send(SendRequest) returns (SendResponse) {}
 }
 
-// Send an email by passing in from, to, subject and a text or html body
+// Send an email by passing in from, to, subject, and a text or html body
 message SendRequest {
-	// the name of the sender
+	// the display name of the sender
 	string from = 1;
 	// the email address of the recipient
 	string to = 2;

emoji/proto/emoji.proto

@@ -45,9 +45,9 @@ message PrintResponse {
 	string text = 1;
 }
 
-// Send an emoji to anyone via SMS
+// Send an emoji to anyone via SMS. Messages are sent in the form '<message> Sent from <from>'
 message SendRequest {
-	// who the message is from e.g Alice
+	// the name of the sender from e.g Alice
 	string from = 1;
 	// phone number to send to (including international dialing code)
 	string to = 2;

file/README.md

@@ -1,5 +1,5 @@
-Store, list and retrieve text files
+Store, list, and retrieve text files
 
 # File Service
 
-Save, list and retrieve text files by project and path.
+Save, list, and retrieve text files. Files can have a path in the same way they would on your computer e.g.`/documents/text-files/file.txt`. Files can optionally be grouped in to projects.

file/proto/file.proto

@@ -56,12 +56,12 @@ message SaveRequest {
 message SaveResponse {
 }
 
-// List file by their project and optionally a path.
+// List files by their project and optionally a path.
 message ListRequest {
 	// Project, required for listing.
 	string project = 1;
 	// Defaults to '/', ie. lists all files in a project.
-	// Supply path if of a folder if you want to list
+	// Supply path to a folder if you want to list
 	// files inside that folder
 	// eg. '/docs'
 	string path = 2;

forex/README.md

@@ -1,8 +1,8 @@
-Foreign Exchange (FX) rates
+Foreign exchange (FX) rates
 
 # Forex Service
 
-Real-time and Historical Foreign Exchange (FX) rates from over 200 world currencies. 
+Real-time and historical foreign exchange (FX) rates for over 200 world currencies. Get the latest rates and bid/ask prices. 
 
 Powered by [Finage](https://finage.co.uk)
 

forex/proto/forex.proto

@@ -10,7 +10,7 @@ service Forex {
 	rpc History(HistoryRequest) returns (HistoryResponse) {}
 }
 
-// Get the last price for a given forex ticker
+// Get the latest price for a given forex ticker
 message PriceRequest {
 	// forex symbol e.g GBPUSD
 	string symbol = 1;
@@ -23,7 +23,7 @@ message PriceResponse {
 	double price = 2;
 }
 
-// Get the last quote for the forex
+// Get the latest quote for the forex
 message QuoteRequest {
 	// the forex symbol e.g GBPUSD
 	string symbol = 1;

geocoding/README.md

@@ -2,5 +2,5 @@ Geocode an address to gps location and the reverse.
 
 # Geocoding Service
 
-The geocoding service provides address to lat lng geocoding as well as the reverse. 
+The geocoding service provides address to latitude longitude geocoding as well as the reverse. 
 It's useful for building mapping or location based services.

geocoding/proto/geocoding.proto

@@ -23,7 +23,7 @@ message Location {
 	double longitude = 2;
 }
 
-// Lookup returns a geocoded address including normalized address and gps coordinates
+// Lookup returns a geocoded address including normalized address and gps coordinates. All fields are optional, provide more to get more accurate results
 message LookupRequest {
 	string address = 1;
 	string city = 2;

go.mod

@@ -1,16 +1,14 @@
 module github.com/micro/services
 
-go 1.14
+go 1.15
 
 require (
-	github.com/HdrHistogram/hdrhistogram-go v1.1.0 // indirect
 	github.com/Masterminds/semver/v3 v3.1.1
 	github.com/PuerkitoBio/goquery v1.6.1
 	github.com/SlyMarbo/rss v1.0.1
 	github.com/asim/mq v0.1.0
 	github.com/cdipaolo/goml v0.0.0-20190412180403-e1f51f713598 // indirect
 	github.com/cdipaolo/sentiment v0.0.0-20200617002423-c697f64e7f10
-	github.com/cpuguy83/go-md2man/v2 v2.0.0 // indirect
 	github.com/crufter/lexer v0.0.0-20120907053443-23fe8c7add01
 	github.com/disintegration/imaging v1.6.2
 	github.com/enescakir/emoji v1.0.0
@@ -32,8 +30,6 @@ require (
 	github.com/mattheath/kala v0.0.0-20171219141654-d6276794bf0e
 	github.com/micro/micro/v3 v3.4.1-0.20210827085315-cdb3e3adc9b3
 	github.com/miekg/dns v1.1.31 // indirect
-	github.com/onsi/ginkgo v1.15.0 // indirect
-	github.com/opentracing/opentracing-go v1.2.0 // indirect
 	github.com/oschwald/geoip2-golang v1.5.0
 	github.com/patrickmn/go-cache v2.1.0+incompatible
 	github.com/paulmach/go.geo v0.0.0-20180829195134-22b514266d33
@@ -46,8 +42,6 @@ require (
 	github.com/tkuchiki/go-timezone v0.2.2
 	github.com/ttacon/builder v0.0.0-20170518171403-c099f663e1c2 // indirect
 	github.com/ttacon/libphonenumber v1.2.1 // indirect
-	github.com/uber/jaeger-client-go v2.29.1+incompatible // indirect
-	github.com/uber/jaeger-lib v2.4.1+incompatible // indirect
 	go.opencensus.io v0.22.4 // indirect
 	golang.org/x/crypto v0.0.0-20210322153248-0c34fe9e7dc2
 	golang.org/x/net v0.0.0-20210226172049-e18ecbb05110

go.sum

@@ -358,8 +358,6 @@ github.com/mattn/go-sqlite3 v1.14.5 h1:1IdxlwTNazvbKJQSxoJ5/9ECbEeaTTyeU7sEAZ5KK
 github.com/mattn/go-sqlite3 v1.14.5/go.mod h1:WVKg1VTActs4Qso6iwGbiFih2UIHo0ENGwNd0Lj+XmI=
 github.com/mattn/go-tty v0.0.0-20180219170247-931426f7535a/go.mod h1:XPvLUNfbS4fJH25nqRHfWLMa1ONC8Amw+mIA639KxkE=
 github.com/matttproud/golang_protobuf_extensions v1.0.1/go.mod h1:D8He9yQNgCq6Z5Ld7szi9bcBfOoFv/3dc6xSMkL2PC0=
-github.com/micro/micro/v3 v3.3.1-0.20210611161948-fd9821dd4f52 h1:laHYhHMiGtbv/jjykUubxxGW+1HAgTi0RFDsNOnwXxg=
-github.com/micro/micro/v3 v3.3.1-0.20210611161948-fd9821dd4f52/go.mod h1:0NVo+HuGK22cbFqkLe59rGZZeXh2++XBfhU+xheOh8g=
 github.com/micro/micro/v3 v3.4.1-0.20210827085315-cdb3e3adc9b3 h1:oS7027tNGjfpLeLOIFTHF06xXGJ2HjHXfk+8VaU19AY=
 github.com/micro/micro/v3 v3.4.1-0.20210827085315-cdb3e3adc9b3/go.mod h1:cgV1bNfRLOE4vytanTo+N/QvjsdTRJRKTVqKq6XH7AA=
 github.com/miekg/dns v1.1.15/go.mod h1:W1PPwlIAgtquWBMBEV9nkV9Cazfe8ScdGz/Lj7v3Nrg=

helloworld/proto/helloworld.proto

@@ -18,9 +18,10 @@ message Response {
 	string message = 1;
 }
 
-// Stream returns a streaming helloworld response
+// Stream returns a stream of "Hello $name" responses
 message StreamRequest {
 	string name = 1;
+	// the number of messages to send back
 	int64 messages = 2;
 }
 

id/README.md

@@ -2,5 +2,5 @@ Generate unique IDs (uuid, snowflake, etc)
 
 # ID Service
 
-The ID service provides unique ID generation. Including uuid, snowflake (64 bit) and bigflake (128 bit)
+The ID service provides unique ID generation. Including UUID, [snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) (64 bit) and [bigflake](https://archive.is/2015.07.08-082503/http://www.boundary.com/blog/2012/01/flake-a-decentralized-k-ordered-unique-id-generator-in-erlang/) (128 bit)
 

image/README.md

@@ -1,5 +1,5 @@
-Quickly upload, resize and convert images
+Quickly upload, resize, and convert images
 
 # Image Service
 
-The image service provides upload, resize and image conversion. It provides a cdn for uploaded images and a simple API.
+The image service provides upload, resize, and image conversion. It provides a CDN for uploaded images and a simple API.

ip/README.md

@@ -2,4 +2,4 @@ IP to geolocation lookup
 
 # IP Service
 
-The IP service provides IP to geolocation lookup including asn, city, country, timezone and lat/long.
+The IP service provides IP to geolocation lookup including asn, city, country, timezone, and latitude/longitude.

location/README.md

@@ -2,6 +2,9 @@ Real time GPS location tracking and search
 
 # Location Service
 
-Send, store and search real time gps point data and tracking info using the location API. 
+Send, store, and search real time GPS point data and tracking information using the location API. 
+- Record and retrieve the locations of your entities
+- Perform location based search of them including filters
+
 Build powerful map rendered views with up to the second updated points on the map.
 

location/proto/location.proto

@@ -53,7 +53,7 @@ message SearchRequest {
 	double radius = 2;
 	// type of entities to filter
 	string type = 3;
-	// number of entities to return
+	// Maximum number of entities to return
 	int64 numEntities = 4;
 }
 

otp/README.md

@@ -2,4 +2,4 @@ One time password generation
 
 # OTP Service
 
-Generate one time passwords (OTP) for any unique id, email or user. Codes are valid for up to 60 seconds.
+Generate one time passwords (OTP) for any unique id, email, or user. Codes have a user configurable expiry time.

otp/proto/otp.proto

@@ -33,6 +33,6 @@ message ValidateRequest {
 }
 
 message ValidateResponse {
-	// returns true if successful
+	// returns true if the code is valid for the ID
 	bool success = 1;
 }

postcode/README.md

@@ -1,5 +1,5 @@
-Instant and fast postcode lookup
+Fast UK postcode lookup
 
 # Postcode Service
 
-Lookup postcodes for their related country, region and additional information.
+Lookup UK postcodes for their related latitude/longitude, region, and additional information.

postcode/proto/postcode.proto

@@ -33,7 +33,7 @@ message LookupResponse {
 	double longitude = 7;
 }
 
-// Validate a postcode. Should return valid: true or valid: false
+// Validate a postcode.
 message ValidateRequest {
 	// UK postcode e.g SW1A 2AA
 	string postcode = 1;
@@ -41,6 +41,7 @@ message ValidateRequest {
 }
 
 message ValidateResponse {
+	// Is the postcode valid (true) or not (false)
 	bool valid = 1;
 }
 

routing/README.md

@@ -3,6 +3,6 @@ Etas, routes and turn by turn directions
 # Routing Service
 
 The routing service provides a faster and cheaper alternative to the Google Maps API. 
-Get etas, routes and turn by turn directions all from openstreetmap data. 
+Get etas, routes, and turn by turn directions all from OpenStreetMap data. 
 
 Powered by [OSRM](http://project-osrm.org/)

routing/proto/routing.proto

@@ -56,7 +56,7 @@ message Direction {
 	repeated Intersection intersections = 7;
 }
 
-// Turn by turn directions from a starting and endpoint including maneuvers and bearings
+// Turn by turn directions from a start point to an end point including maneuvers and bearings
 message DirectionsRequest {
 	// The staring point for the journey
 	Point origin = 1;
@@ -81,7 +81,7 @@ message EtaRequest {
 	Point origin = 1;
 	// The end point for the eta calculation
 	Point destination = 2;
-	// type of transport e.g car, foot, bicycle
+	// type of transport. Only "car" is supported currently.
 	string type = 3;
 	// speed in kilometers
 	double speed = 4;

rss/README.md

@@ -2,5 +2,5 @@ RSS feed crawler and reader
 
 # RSS Service
 
-Provides a simple way to crawl and index RSS feeds making them accessibly via a simple unified API.
+Provides a simple way to crawl and index RSS feeds making them accessible via a simple unified API.
 

rss/proto/rss.proto

@@ -41,7 +41,7 @@ message Entry {
 	string date = 7;
 }
 
-// Add a new RSS feed with a name, url and category
+// Add a new RSS feed with a name, url, and category
 message AddRequest {
 	// rss feed name
 	// eg. a16z

time/README.md

@@ -1,7 +1,7 @@
-Time, date and timezone info
+Time, date, and timezone info
 
 # Time Service
 
-Get the time, date and timezone info for any given location in the world. 
+Get the time, date, and timezone info for any given location in the world. 
 
 Powered by [Weather API](https://weatherapi.com)

url/README.md

@@ -1,5 +1,5 @@
-URL shortening, sharing and tracking
+URL shortening, sharing, and tracking
 
 # URL Service
 
-The url service provides one time short urls for anything. Shorten, share and track the usage.
+The url service provides one time short urls for anything. Shorten, share, and then track the usage.

url/proto/url.proto

@@ -30,8 +30,7 @@ message URLPair {
 	int64 hitCount = 5;
 }
 
-// List shortened URLs. It has no input parameters, as it will take
+// List information on all the shortened URLs that you have created
-// the user ID from the token and list the user's (caller's) shortened URLs.
 message ListRequest {
 	// filter by short URL, optional
 	string shortURL = 2;
@@ -42,8 +41,6 @@ message ListResponse {
 }
 
 // Proxy returns the destination URL of a short URL.
-// Proxy resolves even URLs not owned by the token holder,
-// unlike the List endpoint.
 message ProxyRequest {
 	// short url ID, without the domain, eg. if your short URL is
 	// `m3o.one/u/someshorturlid` then pass in `someshorturlid`

user/proto/user.proto

@@ -163,21 +163,22 @@ message VerifyEmailResponse{
 }
 
 // Send a verification email
-// to the user being signed up. Email from will be 'support@m3o.com',
+// to the user being signed up. Email from will be from 'support@m3o.com',
 // but you can provide the title and contents.
-// Use $micro_verification_link template variable in the content.
+// The verification link will be injected in to the email as a template variable, $micro_verification_link.
-message SendVerificationEmailRequest{
-	string email = 1;
-	string subject = 2;
 // Example: 'Hi there, welcome onboard! Use the link below to verify your email: $micro_verification_link'
 // The variable will be replaced with an actual url that will look similar to this:
 // 'https://user.m3o.com/user/verify?token=a-verification-token&rediretUrl=your-redir-url'
+
+message SendVerificationEmailRequest{
+	string email = 1;
+	string subject = 2;
+	// Text content of the email. Don't forget to include the string '$micro_verification_link' which will be replaced by the real verification link
 	// HTML emails are not available currently.
 	string textContent = 3;
 	string redirectUrl = 4;
 	string failureRedirectUrl = 5;
-	// While the from email address can't be changed,
+	// Display name of the sender for the email. Note: the email address will still be 'support@m3o.com'
-	// the from name (ie. sender name) can.
 	string fromName = 6;
 }
 

weather/proto/weather.proto

@@ -61,7 +61,7 @@ message ForecastResponse {
 	string timezone = 6;
 	// the local time
 	string local_time = 7;
-	// forecase for the next number of days
+	// forecast for the next number of days
 	repeated Forecast forecast = 8;
 }