Fix typos and increase consistency of docs #3261
Conversation
There was a problem hiding this comment.
Reviewed 8 of 8 files at r1.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on @mlegner)
a discussion (no related file):
Make sure that scion.sh lint passes locally. (we have linting on MD files)
doc/BeaconService.md, line 20 at r1 (raw file):
It reuses the existing building blocks for go services: * [go/lib/env](/go/lib/env): Is used for configuration and setup of the service.
Those links don't work. Probably you'd need to prefix them with ../
doc/BeaconService.md, line 41 at r1 (raw file):
interface-state-keeping
why use dashes here but above not?
doc/BeaconService.md, line 88 at r1 (raw file):
[policy](/doc/PathPolicy.md)
Nope, that's not the same policy. Please remove this link.
doc/PathReversal.md, line 5 at r1 (raw file):
(i.e., if a router is doing the reversal).
Wouldn't the correct form be , i.e. if a router... without parentheses but with a comma instead?
doc/PathReversal.md, line 16 at r1 (raw file):
the common header is updated to point to the next routeable (i.e., not `VERIFY_ONLY`) Hop Field
routeable, i.e. not VERIFY_ONLY hop field ?
There was a problem hiding this comment.
Reviewable status: 6 of 8 files reviewed, 6 unresolved discussions (waiting on @lukedirtwalker)
a discussion (no related file):
Previously, lukedirtwalker (Lukas Vogel) wrote…
Make sure that
scion.sh lintpasses locally. (we have linting on MD files)
Done.
doc/BeaconService.md, line 20 at r1 (raw file):
Previously, lukedirtwalker (Lukas Vogel) wrote…
Those links don't work. Probably you'd need to prefix them with
../
Done.
doc/BeaconService.md, line 41 at r1 (raw file):
Previously, lukedirtwalker (Lukas Vogel) wrote…
interface-state-keepingwhy use dashes here but above not?
Here, it is used as an adjective ("compound modifier") and it is recommended to hyphenate it for clarity. But I can revert that if you prefer.
doc/BeaconService.md, line 88 at r1 (raw file):
Previously, lukedirtwalker (Lukas Vogel) wrote…
[policy](/doc/PathPolicy.md)Nope, that's not the same policy. Please remove this link.
Done. Sorry, I misunderstood the relation.
doc/PathReversal.md, line 5 at r1 (raw file):
Previously, lukedirtwalker (Lukas Vogel) wrote…
(i.e., if a router is doing the reversal).Wouldn't the correct form be
, i.e. if a router...without parentheses but with a comma instead?
Phrases like "i.e." and "e.g." should be followed by a comma and can be preceded by multiple punctuation symbols (semicolon, em dash, paretheses, comma). See https://www.chicagomanualofstyle.org/book/ed17/part2/ch06/psec051.html for details.
doc/PathReversal.md, line 16 at r1 (raw file):
Previously, lukedirtwalker (Lukas Vogel) wrote…
the common header is updated to point to the next routeable (i.e., not `VERIFY_ONLY`) Hop Fieldrouteable, i.e. not
VERIFY_ONLYhop field ?
See previous.
There was a problem hiding this comment.
Reviewed 2 of 2 files at r2.
Reviewable status:complete! all files reviewed, all discussions resolved
Multiple typos and text improvements in doc/* and go/beacon_srv/main.go
Multiple typos and minor text improvements in
doc/*andgo/beacon_srv/main.go.This change is