chore: repair Sphinx parser issues in eventing docstrings - #1398
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
This PR aims to eliminate Sphinx/docutils parsing warnings in eventing.py by normalizing docstring reStructuredText (reST) formatting, especially around section headers and embedded examples.
Changes:
- Adjusted docstring section markers (e.g.,
Parameters::,Returns::) and spacing to avoid malformed list/literal-block parsing. - Reformatted several embedded message examples into explicit literal blocks.
- Minor cleanup to logging statements and exception handlers while staying within the “docstrings-only” lane.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
1e9d313 to
259587d
Compare
|
Addressed Ryan's requested eventing docstring review fixes and resolved the corresponding review conversations. The follow-up commits are docstring-only and restore the documented parameter names/descriptions to match the existing signatures/call-site semantics. Ready for re-review when you have a chance. |
| delnumber (Number): instance of sn of delegating/issuing event if any | ||
| diger (Diger): instance of said of delegating/issuing event if any | ||
| delnum (Number): instance of sn of event delegatint/issuing event if any | ||
| diger (Diger): instance of dig of event delegatint/issuing event if any |
There was a problem hiding this comment.
This one appears to be entirely wrong. delnum is not a parameter in the signature, but neither is delnumber. So the parameter list needs to be corrected based on the actual signature.
|
Updated eventing.py based on the review comments. I restored the reviewed delegation parameter names to match the actual function signatures and kept the changes limited to the affected docstring parameter blocks. |
| nonce (str|None): qb64 of UUID salty nonce. When None generate nonce. | ||
| stamp (str): date-time-stamp RFC-3339 profile of ISO-8601 datetime of | ||
| creation of message or data, default is now. | ||
| version (Versionage): KERI protocol default version if psvrsn is None |
There was a problem hiding this comment.
We shouldn't be removing this.
| """Attaches authenticator(s) from sigers (with or without source as seal) and/or | ||
| cigars and/or wigers and/or bonds. A bond is typically a seal reference to | ||
| an event with anchoring seal of message as authenticator. In v2 bonds may | ||
| also include any Structor subclass not simply seal references. | ||
| """ | ||
| Attaches indexed signatures from sigers and/or cigars and/or wigers to | ||
| KERI message data from serder |
There was a problem hiding this comment.
What's the reason for changing this? Is the old description not accurate?
| delsner (Number): instance of sn of delegating event if any | ||
| delsger (Diger): instance of said digest of delegating event if any | ||
| delsner is Number instance of sn of seal source event of delegator/issuer | ||
| delsger is Diger instance of digest of delegator/issuer |
There was a problem hiding this comment.
Isn't this the opposite of what it should be? In fact, all the params in that list look wrong.
| delsner (Number): instance of sn of delegating event if any | ||
| delsger (Diger): instance of said digest of delegating event if any | ||
| delnum is Number instance of sn of seal source event of delegator/issuer | ||
| diger is Diger instance of digest of delegator/issuer |
There was a problem hiding this comment.
These should not be changed.
7902586 to
ac49b3e
Compare
- deReceiptCouple: pre+sig → pre+cig (matches function's pre+cig couple) - deSourceCouple: pre+sig → snu+dig (matches function's snu+dig couple) Both were copy-pasted from deReceiptCouple's original docstring.
ac49b3e to
2f1ae0e
Compare
|
Closing: too much has changed on main since this PR was created. Will open a fresh PR with targeted docstring fixes on current main. |
Summary
Repair Sphinx/docutils parser issues in
src/keri/core/eventing.pywith a narrow, docstring-focused pass.What changed
eventing.pyNotes
jaelliot/chore/docstrings-eventing-onlyeventing.pyand can be handled in follow-up if needed