Skip to content

Docs improvements#2100

Merged
TheBlueMatt merged 1 commit into
lightningdevkit:mainfrom
douglaz:docs_fixes
Mar 21, 2023
Merged

Docs improvements#2100
TheBlueMatt merged 1 commit into
lightningdevkit:mainfrom
douglaz:docs_fixes

Conversation

@douglaz

@douglaz douglaz commented Mar 12, 2023

Copy link
Copy Markdown
Contributor

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.

Comment thread fuzz/src/full_stack.rs
Comment thread lightning/src/ln/chan_utils.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs
Comment thread lightning/src/ln/channelmanager.rs Outdated
@codecov-commenter

codecov-commenter commented Mar 12, 2023

Copy link
Copy Markdown

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.

@tnull tnull left a comment

Copy link
Copy Markdown
Contributor

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).

Comment thread lightning/src/ln/channel.rs Outdated
Comment thread lightning/src/ln/channel.rs
Comment thread lightning/src/ln/channel.rs
Comment thread lightning/src/ln/chan_utils.rs Outdated
Comment thread lightning/src/ln/channel.rs
Comment thread lightning/src/ln/peer_handler.rs Outdated
Comment thread lightning/src/ln/peer_handler.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/chan_utils.rs
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated

@TheBlueMatt TheBlueMatt left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks!

Comment thread lightning/src/ln/channel.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
@douglaz douglaz force-pushed the docs_fixes branch 2 times, most recently from e84874e to 060a399 Compare March 14, 2023 19:54
@douglaz

douglaz commented Mar 14, 2023

Copy link
Copy Markdown
Contributor Author

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

@tnull tnull left a comment

Copy link
Copy Markdown
Contributor

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

douglaz commented Mar 15, 2023

Copy link
Copy Markdown
Contributor Author

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

tnull commented Mar 15, 2023

Copy link
Copy Markdown
Contributor

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.

@TheBlueMatt TheBlueMatt left a comment

Copy link
Copy Markdown
Collaborator

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 :)

Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/mod.rs Outdated
@douglaz

douglaz commented Mar 20, 2023

Copy link
Copy Markdown
Contributor Author

@TheBlueMatt Please double check the changes

Comment thread lightning/src/ln/channelmanager.rs Outdated
@douglaz

douglaz commented Mar 21, 2023

Copy link
Copy Markdown
Contributor Author

I think it's okay now 🤞

Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/channelmanager.rs Outdated
Comment thread lightning/src/ln/peer_handler.rs Outdated
Comment thread lightning/src/ln/mod.rs Outdated
@douglaz

douglaz commented Mar 21, 2023

Copy link
Copy Markdown
Contributor Author

@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