policy: Do a bunch of docs fixes #565
Merged
Conversation
This file contains hidden or 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
The comment on why we use semantic and abstract interchangeable is better placed in the `semantic` module docs.
Currently the `translate_pk` functions on `semantic::Policy` and `concrete::Policy` have exactly the same docs in the `# Examples` section, down to the usage of "abstract" in both. Direct docs readers from one function to the other to see the example.
Put some love and care into the docs in the `policy` module: - Use standard tense on functions - Use full sentences - Fix grammar/spelling/typos - Tidy up rustdoc examples - Use standard section headers (eg, `# Returns`) - Fix links - Use backticks I doubt this is perfect because fixing (and reviewing) docs is a bit boring but I'm confident it is an improvement :) There was a couple of functions that I could not re-write the docs for at the time I did this work but I've misplaced them for now.
apoelstra
approved these changes
Jul 14, 2023
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.
Three patches, the first two simple. The third is a bunch of mixed rustdoc fixes. Just sing out if this is too painful to review. I did this while attempting to understand the module better.