Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updating and formatting the docs #128

Open
1 of 5 tasks
elichai opened this issue Jul 8, 2019 · 4 comments
Open
1 of 5 tasks

Updating and formatting the docs #128

elichai opened this issue Jul 8, 2019 · 4 comments

Comments

@elichai
Copy link
Member

elichai commented Jul 8, 2019 •
edited

I think some modules are underdocumented.
I think some of the docs deserves a redo and at least these are missing:

  • How to use the preallocated structs.
  • Explanations around the traits/enums.
  • Doing something with the fact that ffi is public but shows docs for the fuzzings functions.
  • Fixing failed attempts to bold text (i.e. in the Context trait and in Error::InvalidTweak)
  • Adding some explanation in the Secp256k1 struct about the different situation of different functions for different types of contexts (is there a way in rust docs to make it look a bit better?)
@tcharding tcharding mentioned this issue Nov 18, 2021
Merged
@tcharding
Copy link
Member

tcharding commented Nov 18, 2021 •
edited

Fixing failed attempts to bold text (i.e. in the Context trait and in Error::InvalidTweak)

I think I have resolved this in: #340

Specifically

@tcharding
Copy link
Member

tcharding commented Nov 18, 2021 •
edited

Doing something with the fact that ffi is public but shows docs for the fuzzings functions.

I was unable to see the fuzzing functions that this refers to, is it still relevant?

@elichai
Copy link
Member Author

elichai commented Nov 18, 2021

Doing something with the fact that ffi is public but shows docs for the fuzzings functions.

I was unable to see the fuzzing functions that this refers to, is it still relevant?

Yes, I think this was fixed it #263

apoelstra added a commit that referenced this issue Feb 10, 2022
@apoelstra
Merge #340: Improve documentation
df7520e 
c73eb2f Use 'extra' instead of 'cheap' (Tobin Harding)
c79eb97 Remove unnecessary explanation (Tobin Harding)
f95e91a Use isn't instead of shouldn't (Tobin Harding)
c9e6ca1 Use rust-bitcoin module doc style (Tobin Harding)
3fa6762 Add link to referenced commit (Tobin Harding)
f5e68f3 Add ticks around code snippet (Tobin Harding)
d25431c Use 3rd person tense for function docs (Tobin Harding)
c3be285 Fix size constant docs (Tobin Harding)
5e07e75 Add period to sentences (Tobin Harding)
269bde0 Remove unnecessary capitalisation (Tobin Harding)

Pull request description:

  In a continued effort to find my feet around here, and inspired by issue #128 I've done a codebase wide audit of the docs (primarily just rustdocs but I glanced at `//` docs as well). Each change is in a separate commit so can be removed if resistance is met. (_"resistance is futile"_).

  I've based the stylistic decisions on [work done](rust-bitcoin/rust-bitcoin#704) in rust-bitcoin.

  I believe the only controversial change is the last (commit: da161c9 Use rust-bitcoin module doc style), please review that one carefully.

ACKs for top commit:
  apoelstra:
    ACK c73eb2f

Tree-SHA512: 5ea215de3fd23ca2a4f25d8f8d59a85a299044fe495269c43b621291ea50c58856fa8544e36cc109b7bdb1a7a59bcab8711f30113572ddce4509d3b06ff0d3b6
@tcharding
Copy link
Member

I've come to try and resolve this issue a few times but cannot make progress. If someone wants to post something rough I can extrapolate and do a PR.

@tcharding tcharding mentioned this issue Nov 24, 2022
Merged
apoelstra added a commit that referenced this issue Nov 24, 2022
@apoelstra
Merge #532: Do trivial docs improvements
efb47e9 
ecdad39 context: Improve rustdocs (Tobin C. Harding)
e945751 schnorr: Improve rustdocs (Tobin C. Harding)
47f19a7 Use lowercase for schnorr (Tobin C. Harding)
27b3e92 Do trivial cleanup to module level docs (Tobin C. Harding)

Pull request description:

  Audit of docs in `rust-secp256k1` and do a few trivial fixes. The docs are in pretty good condition, they just need more content as described in #128 if that issue is still valid.

ACKs for top commit:
  apoelstra:
    ACK ecdad39

Tree-SHA512: 7466090325e02331f11e34cd38625541fbe8e642882afa6ddf2cf5d11ed669c7b2b48fd5b819915392760f4c6ef4ee460c2e622b3af648f99906c3ac408045d4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@elichai @tcharding