consensus_encoding: Go over docs with a fine toothcomb#5899
consensus_encoding: Go over docs with a fine toothcomb#5899apoelstra merged 7 commits intorust-bitcoin:masterfrom
Conversation
db8d39b to
76e6cb0
Compare
|
Ooph had typo in commit log (title). PR is docs only if I removed the whitespace change. Electing to leave for Andrew to merge. |
|
This looks great. I went over the docs. I'm happy to merge this and then to just cut 1.0. But to be a bit pedantic:
I think we can defer these to a point release. And we know (I think) that we want to do a 1.1 eventually with hex support, once we've gotten the hex encoding stuff worked out properly. |
Pedant away! I'd prefer to have a go at getting all your observations fixed. I can do it today. Also I rekon we want #5897 in before we do 1.0 so we don't have to do 1.1 immediately.
Oh I did not have this on my radar. What exactly are you referring to pls? |
`rust-bitcoin` project uses 100 column width for rustdoc. Now that `consensus_encoding` is a hair width away from 1.0 update all the rustdocs to use it. However do not be dogmatic; if a doc is better with slightly different colum width then do so.
This is a style change; fit in with the rest of the repo.
Mention all the free standing functions in the crate level docs.
Add an examples section to the rustdocs for the two public macros.
In order to make the HTML docs render more clearly it would be nice to have all the errors separate. We recently introduced a policy for doing this repo wide. Add a public `error` submodule and re-export all errors at the crate root. Because of anomalies in how `cargo` renders docs for re-exports between types and modules explicitly use `doc(inline)` and `no_inline` so we get exactly the behaviour we desire.
76e6cb0 to
34281a5
Compare
|
Please note the final patch may seem controversial but is inline with recently introduced policy for error submodules. |
|
fmt issues are in |
|
Not sure how we got green CI with the issues this introduces because it changes the API text files (in non-meaningful ways). |
|
Oof, it did have a red X for the API files, but it was way at the bottom where I didn't see it, and I ignored the "CI failed" because of the fmt job. |
I guessed this, I've already started ignoring CI too because of it. This red-always job may not be such a good idea. |
Nick has this crate clean AF and ready to
1.0. I just went over the whole crate docs for any minute improvement.Add an
errorsubmodule. This is a docs related change because it is explicitly done to improve the HTML rendering of the docs.