Improve godoc output #250
Merged
Improve godoc output #250
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Unlike other documentation tools, godoc does not parse markdown syntax. In Go, documentation comments are simple sentences with no added markup. See https://blog.golang.org/godoc.
- It is irrelevant to explain "how" the SDK is initialized (no need to talk about Client and Hub -- those interested in the details will read the source code). - Document when the returned error is non-nil. Many people might ignore the error, so it is at least a start to document when initializing the SDK might fail.
Note that gocertifi was removed long ago in v0.0.1-beta.3.
- Group related constants together so that we can introduce them all with a single comment, producing cleaner godoc output. - Clean up doc comments of unexported values.
Fixes a typo "atleast" by rewriting and making the comment more concise.
https://github.com/golang/go/wiki/CodeReviewComments#comment-sentences And add godot linter to prevent regression.
Sometimes globals make sense. We do use globals intentionally, and the linter has not stopped us from doing so. The comments to disable the linter unfortunately end up in godoc output as additional noise, thus this commit removes it as part of making godoc output look better.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
One step towards better godoc output / better docs at godoc.org; not perfect.
Before
No package overview:
Sometimes messy output on the console:
After
Basic package overview:
Better output on the console: