Permalink
Browse files

Docs: Restructured README to Installation, Usage and Examples section…

…s [ci skip]
  • Loading branch information...
dcodeIO committed Mar 21, 2017
1 parent 1c9055d commit 320dea5a1d1387c72759e10a17afd77dc48c3de0
Showing with 19 additions and 13 deletions.
  1. +19 −13 README.md
@@ -8,11 +8,11 @@
Contents
--------
* [Usage](#usage)<br />
* [Installation](#installation)<br />
How to include protobuf.js in your project.
* [Distributions](#distributions)<br />
A brief introduction to the available distributions and their use cases.
* [Usage](#usage)<br />
A brief introduction to using the toolset.
* [Examples](#examples)<br />
A few examples to get you started.
@@ -32,7 +32,7 @@ Contents
* [Building](#building)<br />
How to build the library and its components yourself.
Usage
Installation
---------------
### node.js
@@ -61,16 +61,15 @@ Production:
The `protobuf` namespace will always be available globally / also supports AMD loaders.
Distributions
-------------
### Distributions
The library supports both reflection-based and code-based use cases:
1. Parsing protocol buffer definitions (.proto files) to reflection
2. Loading JSON descriptors to reflection
3. Generating static code without any reflection features
There is a suitable distribution for each of these:
Where bundle size is a factor, there is a suitable distribution for each of these:
| | Gzipped | Downloads | How to require | Description
|---------|---------|------------------------------|---------------------------------|-------------
@@ -84,12 +83,10 @@ In case of doubt you can just use the full library.
[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light
[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal
Examples
--------
### Understanding the toolset
Usage
-----
For optimal performance, protobuf.js tries to avoid redundant assertions. Instead, it provides multiple methods, each doing just one thing.
For [performance](#performance) reasons, protobuf.js provides multiple methods per message type with each of them doing just one thing. This avoids redundant assertions where messages are already known to be valid but also requires explicit verification where necessary. Note that `Message` refers to any message below.
* **Message.verify**(message: *Object*): *?string*<br />
explicitly performs verification prior to encoding / converting a plain object (i.e. where data comes from user input). Instead of throwing, it returns the error message as a string, if any.
@@ -108,6 +105,9 @@ For optimal performance, protobuf.js tries to avoid redundant assertions. Instea
var buffer = AwesomeMessage.encode(message).finish();
```
* **Message.encodeDelimited**(message: *Message|Object*[, writer: *Writer*]): *Writer*<br />
additionally prepends the length of the message as a varint.
* **Message.decode**(reader: *Reader|Uint8Array*): *Message*<br />
is a message specific decoder expecting a valid buffer. If required fields are missing, it throws a `protobuf.util.ProtocolError` with an `instance` property set to the so far decoded message - otherwise an `Error`. The result is a runtime message.
@@ -121,6 +121,9 @@ For optimal performance, protobuf.js tries to avoid redundant assertions. Instea
}
```
* **Message.decodeDelimited**(reader: *Reader|Uint8Array*): *Message*<br />
additionally reads the length of the meessage prepended as a varint.
* **Message.create**(properties: *Object*): *Message*<br />
quickly creates a new runtime message from known to be valid properties without any conversion being performed.
@@ -144,9 +147,12 @@ For optimal performance, protobuf.js tries to avoid redundant assertions. Instea
// converts enums, longs and bytes to their string representation and includes default values
```
Examples
--------
### Using .proto files
It's possible to load existing .proto files using the full library, which parses and compiles the definitions to ready to use (reflection-based) message classes:
It is possible to load existing .proto files using the full library, which parses and compiles the definitions to ready to use (reflection-based) message classes:
```protobuf
// awesome.proto

0 comments on commit 320dea5

Please sign in to comment.