Documentation/learning/api.md: fix typos #8996

tinx · 2017-12-10T14:30:54Z

Just some minor fixes in api.md.

codecov-io · 2017-12-10T15:33:46Z

Codecov Report

❗ No coverage uploaded for pull request base (master@809b0d7). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #8996   +/-   ##
=========================================
  Coverage          ?   75.84%           
=========================================
  Files             ?      359           
  Lines             ?    29825           
  Branches          ?        0           
=========================================
  Hits              ?    22622           
  Misses            ?     5619           
  Partials          ?     1584

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 809b0d7...5a2b0dd. Read the comment docs.

xiang90 · 2017-12-11T19:48:14Z

/cc @spzala can you take a look of this?

spzala · 2017-12-11T21:52:19Z

@xiang90 yup sounds great.

spzala

In-line review comments. Thanks!

spzala · 2017-12-12T04:25:08Z

Documentation/learning/api.md

@@ -47,7 +47,7 @@ message ResponseHeader {

 An application may read the Cluster_ID (Member_ID) field to ensure it is communicating with the intended cluster (member).

-Applications can use the `Revision` to know the latest revision of the key-value store. This is especially useful when applications specify a historical revision to make time `travel query` and wish to know the latest revision at the time of the request.
+Applications can use the `Revision` to know the latest revision of the key-value store. This is especially useful when applications specify a historical revision to make a `time travel query` and wish to know the latest revision at the time of the request.


add "field" after Revision for consistency and better reading i.e. Applications can use the Revision field to...

spzala · 2017-12-12T04:27:35Z

Documentation/learning/api.md

@@ -47,7 +47,7 @@ message ResponseHeader {

 An application may read the Cluster_ID (Member_ID) field to ensure it is communicating with the intended cluster (member).


Cluster_ID and Member_ID should be emphasized as Cluster_ID and Member_ID to be consistent with other fields (e.g. Revision or Raft_Term). Also I think since they are two different field, re-writing "Cluster_ID (Member_ID)" as "Cluster_ID or Member_ID" would be proper. Thanks!

spzala · 2017-12-12T04:36:17Z

Documentation/learning/api.md

@@ -86,7 +86,7 @@ In addition to just the key and value, etcd attaches additional revision metadat

 etcd maintains a 64-bit cluster-wide counter, the store revision, that is incremented each time the key space is modified. The revision serves as a global logical clock, sequentially ordering all updates to the store. The change represented by a new revisions is incremental; the data associated with a revision is the data that changed the store. Internally, a new revision means writing the changes to the backend's B+tree, keyed by the incremented revision.


Suggest to change "a new revisions ..." to "a new revision ..."

spzala · 2017-12-12T04:36:32Z

Documentation/learning/api.md

@@ -86,7 +86,7 @@ In addition to just the key and value, etcd attaches additional revision metadat

 etcd maintains a 64-bit cluster-wide counter, the store revision, that is incremented each time the key space is modified. The revision serves as a global logical clock, sequentially ordering all updates to the store. The change represented by a new revisions is incremental; the data associated with a revision is the data that changed the store. Internally, a new revision means writing the changes to the backend's B+tree, keyed by the incremented revision.

-Revisions become more valuable when taking considering etcd3's [multi-version concurrency control][mvcc] backend. The MVCC model means that the key-value store can be viewed from past revisions since historical key revisions are retained. The retention policy for this history can be configured by cluster administrators for fine-grained storage management; usually etcd3 discards old revisions of keys on a timer. A typical etcd3 cluster retains superseded key data for hours. This also buys reliable handling for long client disconnection, not just transient network disruptions: watchers simply resume from the last observed historical revision. Similarly, to read from the store at a particular point-in-time, read requests can be tagged with a revision to return keys from a view of the key space at the point in time that revision was committed.
+Revisions become more valuable when considering etcd3's [multi-version concurrency control][mvcc] backend. The MVCC model means that the key-value store can be viewed from past revisions since historical key revisions are retained. The retention policy for this history can be configured by cluster administrators for fine-grained storage management; usually etcd3 discards old revisions of keys on a timer. A typical etcd3 cluster retains superseded key data for hours. This also buys reliable handling for long client disconnection, not just transient network disruptions: watchers simply resume from the last observed historical revision. Similarly, to read from the store at a particular point-in-time, read requests can be tagged with a revision to return keys from a view of the key space at the point in time that revision was committed.


Suggest to replace "This also buys reliable handling..." to "This also provides reliable handling..". (if word 'buys' is not used for a special purpose).

spzala · 2017-12-12T04:45:44Z

Documentation/learning/api.md

@@ -86,7 +86,7 @@ In addition to just the key and value, etcd attaches additional revision metadat

 etcd maintains a 64-bit cluster-wide counter, the store revision, that is incremented each time the key space is modified. The revision serves as a global logical clock, sequentially ordering all updates to the store. The change represented by a new revisions is incremental; the data associated with a revision is the data that changed the store. Internally, a new revision means writing the changes to the backend's B+tree, keyed by the incremented revision.

-Revisions become more valuable when taking considering etcd3's [multi-version concurrency control][mvcc] backend. The MVCC model means that the key-value store can be viewed from past revisions since historical key revisions are retained. The retention policy for this history can be configured by cluster administrators for fine-grained storage management; usually etcd3 discards old revisions of keys on a timer. A typical etcd3 cluster retains superseded key data for hours. This also buys reliable handling for long client disconnection, not just transient network disruptions: watchers simply resume from the last observed historical revision. Similarly, to read from the store at a particular point-in-time, read requests can be tagged with a revision to return keys from a view of the key space at the point in time that revision was committed.
+Revisions become more valuable when considering etcd3's [multi-version concurrency control][mvcc] backend. The MVCC model means that the key-value store can be viewed from past revisions since historical key revisions are retained. The retention policy for this history can be configured by cluster administrators for fine-grained storage management; usually etcd3 discards old revisions of keys on a timer. A typical etcd3 cluster retains superseded key data for hours. This also buys reliable handling for long client disconnection, not just transient network disruptions: watchers simply resume from the last observed historical revision. Similarly, to read from the store at a particular point-in-time, read requests can be tagged with a revision to return keys from a view of the key space at the point in time that revision was committed.


Replace “point in time” with “point-in-time” in the “…at the point in time that revision was committed.” sentence for consistency.

spzala · 2017-12-12T04:58:42Z

Since we are fixing small things in this particular doc page, I also have few more comments:

I would suggest to change “Request to “request” in the “By convention, ranges for a Request are denoted ..” sentence under the “Key ranges” section for consistency.

Change DeleteRange to DeleteRange in the “Prev_Kv - a list of all key-value pairs deleted by the DeleteRange operation.” sentence for consistency under the “DeleteRange” section.

Change “If” to If’ in the “All transactions are guarded by a conjunction of comparisons, similar to an "If" statement. “ under “Transaction” section.

Change “Watch” to Watch in the “The Watch API provides an event-based interface…” sentence in the “Watch API” section.

Please let me know if have questions. Thanks!

A few words have been emphasized to be consistent with the rest of the text. Also, some phrases have been altered for better readability.

tinx · 2017-12-12T17:55:00Z

Hello, @spzala. Thanks for your review.

I made another commit containing your suggestions. :)

xiang90 · 2017-12-12T18:18:32Z

lgtm

spzala · 2017-12-12T18:21:30Z

@tinx thanks for addressing all the comments :-)

spzala · 2017-12-12T18:21:38Z

lgtm

xiang90 · 2017-12-12T21:22:57Z

merging

Documentation/learning/api.md: fix typos

5f24a81

spzala reviewed Dec 12, 2017

View reviewed changes

Documentation/learning/api.md: fix markup, wording

5a2b0dd

A few words have been emphasized to be consistent with the rest of the text. Also, some phrases have been altered for better readability.

xiang90 merged commit c886bda into etcd-io:master Dec 12, 2017

tinx deleted the api_md_typo_fixes branch December 13, 2017 21:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation/learning/api.md: fix typos #8996

Documentation/learning/api.md: fix typos #8996

tinx commented Dec 10, 2017

codecov-io commented Dec 10, 2017 •

edited

Loading

xiang90 commented Dec 11, 2017

spzala commented Dec 11, 2017

spzala left a comment

spzala Dec 12, 2017

spzala Dec 12, 2017

spzala Dec 12, 2017

spzala Dec 12, 2017

spzala Dec 12, 2017 •

edited

Loading

spzala commented Dec 12, 2017 •

edited

Loading

tinx commented Dec 12, 2017

xiang90 commented Dec 12, 2017

spzala commented Dec 12, 2017

spzala commented Dec 12, 2017

xiang90 commented Dec 12, 2017

		@@ -47,7 +47,7 @@ message ResponseHeader {

		An application may read the Cluster_ID (Member_ID) field to ensure it is communicating with the intended cluster (member).

		@@ -86,7 +86,7 @@ In addition to just the key and value, etcd attaches additional revision metadat

		etcd maintains a 64-bit cluster-wide counter, the store revision, that is incremented each time the key space is modified. The revision serves as a global logical clock, sequentially ordering all updates to the store. The change represented by a new revisions is incremental; the data associated with a revision is the data that changed the store. Internally, a new revision means writing the changes to the backend's B+tree, keyed by the incremented revision.

Documentation/learning/api.md: fix typos #8996

Documentation/learning/api.md: fix typos #8996

Conversation

tinx commented Dec 10, 2017

codecov-io commented Dec 10, 2017 • edited Loading

Codecov Report

xiang90 commented Dec 11, 2017

spzala commented Dec 11, 2017

spzala left a comment

Choose a reason for hiding this comment

spzala Dec 12, 2017

Choose a reason for hiding this comment

spzala Dec 12, 2017

Choose a reason for hiding this comment

spzala Dec 12, 2017

Choose a reason for hiding this comment

spzala Dec 12, 2017

Choose a reason for hiding this comment

spzala Dec 12, 2017 • edited Loading

Choose a reason for hiding this comment

spzala commented Dec 12, 2017 • edited Loading

tinx commented Dec 12, 2017

xiang90 commented Dec 12, 2017

spzala commented Dec 12, 2017

spzala commented Dec 12, 2017

xiang90 commented Dec 12, 2017

codecov-io commented Dec 10, 2017 •

edited

Loading

spzala Dec 12, 2017 •

edited

Loading

spzala commented Dec 12, 2017 •

edited

Loading