tweaks to docs (#200)

2026-01-11 10:54:28 +00:00 · 2021-09-02 15:23:24 +01:00
parent 2e5af32faf
commit d378ef2de5
39 changed files with 83 additions and 88 deletions
--- a/.github/workflows/integration.yml
+++ b/.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
--- a/.github/workflows/tests.yml
+++ b/.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
--- a/answer/proto/answer.proto
+++ b/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;
--- a/cache/README.md
+++ b/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.
--- a/cache/proto/cache.proto
+++ b/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;
 }
--- a/crypto/README.md
+++ b/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)
--- a/crypto/proto/crypto.proto
+++ b/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;
--- a/db/README.md
+++ b/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.
--- a/db/proto/db.proto
+++ b/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;
 }

--- a/email/README.md
+++ b/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)

--- a/email/proto/email.proto
+++ b/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;
--- a/emoji/proto/emoji.proto
+++ b/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;
--- a/file/README.md
+++ b/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.
--- a/file/proto/file.proto
+++ b/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;
--- a/forex/README.md
+++ b/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)

--- a/forex/proto/forex.proto
+++ b/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;
--- a/geocoding/README.md
+++ b/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.
--- a/geocoding/proto/geocoding.proto
+++ b/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;
--- a/go.mod
+++ b/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
--- a/go.sum
+++ b/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=
--- a/helloworld/proto/helloworld.proto
+++ b/helloworld/proto/helloworld.proto
@@ -18,10 +18,11 @@ message Response {
 	string message = 1;
 }

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

 message StreamResponse {
--- a/id/README.md
+++ b/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)

--- a/image/README.md
+++ b/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.
--- a/ip/README.md
+++ b/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.
--- a/location/README.md
+++ b/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.

--- a/location/proto/location.proto
+++ b/location/proto/location.proto
@@ -16,9 +16,9 @@ service Location {

 // A point is a GPS coordinate.
 message Point {
-        double latitude = 1;
-        double longitude = 2;
-        int64 timestamp = 3;
+	double latitude = 1;
+	double longitude = 2;
+	int64 timestamp = 3;
 }

 message Entity {
@@ -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;
 }

--- a/otp/README.md
+++ b/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.
--- a/otp/proto/otp.proto
+++ b/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;
 }
--- a/postcode/README.md
+++ b/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.
--- a/postcode/proto/postcode.proto
+++ b/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;
 }

--- a/routing/README.md
+++ b/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/)
--- a/routing/proto/routing.proto
+++ b/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;
--- a/rss/README.md
+++ b/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.

--- a/rss/proto/rss.proto
+++ b/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
--- a/time/README.md
+++ b/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)
--- a/url/README.md
+++ b/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.
--- a/url/proto/url.proto
+++ b/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
-// the user ID from the token and list the user's (caller's) shortened URLs.
+// List information on all the shortened URLs that you have created
 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`
--- a/user/proto/user.proto
+++ b/user/proto/user.proto
@@ -154,7 +154,7 @@ message LogoutResponse {

 // Verify the email address of an account from a token sent in an email to the user.
 message VerifyEmailRequest {
-        // The token from the verification email
+	// The token from the verification email
 	string token = 1;
 }

@@ -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.
+// 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;
-	// 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'
+	// 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,
-	// the from name (ie. sender name) can.
+	// Display name of the sender for the email. Note: the email address will still be 'support@m3o.com'
 	string fromName = 6;
 }

--- a/weather/proto/weather.proto
+++ b/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;
 }