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.

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

Docs improvements #2100

Merged
merged 1 commit into from
Mar 21, 2023
Merged

Docs improvements #2100

merged 1 commit into from
Mar 21, 2023

Conversation

douglaz
Copy link
Contributor

@douglaz douglaz commented Mar 12, 2023

I was looking at the documentation and found some missing references. Doing that I found minor "bugs" (wrong references). See below for my double check comments.

Please note this change isn't exhaustive, there are still many places where similar changes can be made.

@codecov-commenter
Copy link

codecov-commenter commented Mar 12, 2023

Codecov Report

Patch and project coverage have no change.

Comparison is base (2d213a4) 91.15% compared to head (060a399) 91.15%.

❗ Current head 060a399 differs from pull request most recent head 963d6c4. Consider uploading reports for the commit 963d6c4 to get more accurate results

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2100   +/-   ##
=======================================
  Coverage   91.15%   91.15%           
=======================================
  Files         101      101           
  Lines       48866    48866           
  Branches    48866    48866           
=======================================
  Hits        44544    44544           
  Misses       4322     4322           
Impacted Files Coverage Δ
lightning-invoice/src/utils.rs 96.90% <ø> (ø)
lightning/src/ln/chan_utils.rs 93.75% <ø> (ø)
lightning/src/ln/channelmanager.rs 88.85% <ø> (ø)
lightning/src/ln/mod.rs 95.00% <ø> (ø)
lightning/src/ln/peer_handler.rs 62.62% <ø> (ø)
lightning/src/routing/gossip.rs 89.63% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

Copy link
Contributor

@tnull tnull left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for having a go at this!

I think generally we want to tick or link all references to objects in doc comments. However, for the sake of readability it should generally be enough to link the first occurrence in a paragraph and only tick the rest of the references (there are of course exceptions to this, so def. feel free to link when you think it's needed).

lightning/src/ln/channel.rs Outdated Show resolved Hide resolved
lightning/src/ln/channel.rs Outdated Show resolved Hide resolved
lightning/src/ln/channel.rs Outdated Show resolved Hide resolved
lightning/src/ln/chan_utils.rs Outdated Show resolved Hide resolved
lightning/src/ln/channel.rs Outdated Show resolved Hide resolved
lightning/src/ln/peer_handler.rs Outdated Show resolved Hide resolved
lightning/src/ln/peer_handler.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
Copy link
Collaborator

@TheBlueMatt TheBlueMatt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

lightning/src/ln/channel.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
@douglaz douglaz force-pushed the docs_fixes branch 2 times, most recently from e84874e to 060a399 Compare March 14, 2023 19:54
@douglaz
Copy link
Contributor Author

douglaz commented Mar 14, 2023

Addressed all review comments and moved channel.rs changes to #2104

Copy link
Contributor

@tnull tnull left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

One optional thing you could tackle while you're here is to ensure that any (C-not exported) lines come after a blank line, as these comments are not meant for humans and they'll end up in the module-level docs otherwise. One example to be fixed would be PaymentId, but there are others.

@douglaz
Copy link
Contributor Author

douglaz commented Mar 15, 2023

LGTM.

One optional thing you could tackle while you're here is to ensure that any (C-not exported) lines come after a blank line, as these comments are not meant for humans and they'll end up in the module-level docs otherwise. One example to be fixed would be PaymentId, but there are others.

I think a PR focused on that would be better. I've created #2105
Could you label it good first issue?

@tnull
Copy link
Contributor

tnull commented Mar 15, 2023

I think a PR focused on that would be better. I've created #2105 Could you label it good first issue?

SGTM, even though it might introduce some additional git noise.

Copy link
Collaborator

@TheBlueMatt TheBlueMatt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, your cleanups turned up a bunch of places where the docs are just downright ancient and need updating :)

lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/mod.rs Outdated Show resolved Hide resolved
@douglaz
Copy link
Contributor Author

douglaz commented Mar 20, 2023

@TheBlueMatt Please double check the changes

@douglaz
Copy link
Contributor Author

douglaz commented Mar 21, 2023

I think it's okay now 🤞

lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/channelmanager.rs Outdated Show resolved Hide resolved
lightning/src/ln/peer_handler.rs Outdated Show resolved Hide resolved
lightning/src/ln/mod.rs Outdated Show resolved Hide resolved
@douglaz
Copy link
Contributor Author

douglaz commented Mar 21, 2023

@tnull done

@TheBlueMatt TheBlueMatt merged commit ea15f0f into lightningdevkit:main Mar 21, 2023
@douglaz douglaz deleted the docs_fixes branch March 21, 2023 18:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants