Improve docs crate wide #512
Conversation
|
Needs rebase. |
|
Checked that we don't use |
The grammar on structs that implement `Context` using preallocated memory is slightly incorrect. Attempt to improve the grammar.
The `alloc_only` module already has a docs guard on the "alloc" feature, using an additional docs guard on the `SignOnly`, `VerifyOnly`, `All` enums leads to a redundant feature combination "alloc" and "alloc or std" - we really only require "alloc".
The `ONE_KEY` is only used in two rustdoc examples, as such it unnecessarily pollutes the crate root namespace. We can use `SecretKey::from_str()` with no loss of clarity and remove the `ONE_KEY`. While we are touching the import statements in `secret.rs` elect to remove the hide (use of `#`) for import statements relating to this library. Doing so gives devs all the information they need in one place if they are using the examples to copy code. It is also in line with the rest of the codebase.
0f9d295 to
ec47198
Compare
|
It would have been nice to document this breaking change in the changelog along with the fix of using from_str. Probably not worth doing now but I wanted to mention this for future changes. |
|
I can add a changelog entry, though I don't understand the |
|
@tcharding they can't, becauuse the inner field of |
|
Yes, exactly. The workaround is easy, it just took me some time to discover what happened to the constant. It would have taken less time if I had seen mention of it in the changelog for the version that removed it. |
|
My bad, I'll try be more careful. Sorry for stealing your time @vkgnosis, thanks for reporting it. |
|
Done in #622 |
|
Thank you. You also saved me a bunch of time by working on this library. Much more than was taken by this small problem. I appreciate it. |
ec47198a170afe395ce5227565ed0b52c4937883 Remove ONE_KEY (Tobin C. Harding)
d546c161349fd3ccb17540c6abcc4005370efbb2 Remove cfg docs feature requirements (Tobin C. Harding)
5a7cedef004412e37cf254f53018522d58ca9538 doc: Fix preallocated memory grammar (Tobin C. Harding)
Pull request description:
Read over and improve various parts of the crate documentation. Note this is an API breaking PR because it removes the public `ONE_KEY` type that we exposed when writing the docs for the `secret` module, exposing this type was, in my opinion, a mistake.
ACKs for top commit:
apoelstra:
ACK ec47198a170afe395ce5227565ed0b52c4937883
Tree-SHA512: cf8573e58c9498093b0df3f240501d3ad0a9d65e07d2f7c3a9e4116bac6ba366d3d41ac695f4e79010597124512a43b32b4ecb02b08d81226c527d5f77a1a541
ec47198a170afe395ce5227565ed0b52c4937883 Remove ONE_KEY (Tobin C. Harding)
d546c161349fd3ccb17540c6abcc4005370efbb2 Remove cfg docs feature requirements (Tobin C. Harding)
5a7cedef004412e37cf254f53018522d58ca9538 doc: Fix preallocated memory grammar (Tobin C. Harding)
Pull request description:
Read over and improve various parts of the crate documentation. Note this is an API breaking PR because it removes the public `ONE_KEY` type that we exposed when writing the docs for the `secret` module, exposing this type was, in my opinion, a mistake.
ACKs for top commit:
apoelstra:
ACK ec47198a170afe395ce5227565ed0b52c4937883
Tree-SHA512: cf8573e58c9498093b0df3f240501d3ad0a9d65e07d2f7c3a9e4116bac6ba366d3d41ac695f4e79010597124512a43b32b4ecb02b08d81226c527d5f77a1a541
Read over and improve various parts of the crate documentation. Note this is an API breaking PR because it removes the public
ONE_KEYtype that we exposed when writing the docs for thesecretmodule, exposing this type was, in my opinion, a mistake.