docs: document the new interfaces and conform the eight documents - #15
Merged
Merged
Conversation
Three public entry points had no line in any of the eight documents: joint_follow (added in 97884f3) and license / activate (present since the direct-CDC rewrite, 3d962bb). Record joint_follow in guide section 5.7 and in both READMEs, with the facts read off the firmware rather than the SDK: the accept path clamps q to the soft limits, the firmware slews at its own joint-follow speed table, and the state frame keeps reporting MOVE_MIT_ALL, so the mode field does not tell the host that following is active. Add guide section 5.12 for the license record and the activation call, list license() among the entry points that return no Msg envelope, and add a short README pointer. Verified: 656 passed, 2 skipped (tests/test_doc_examples.py checks every signature and runs every example block against the offline stub).
Section 4 of AGENTS.md (added in fed097a, after the documents were rewritten in PR #2) had never been applied to the documents themselves. - Strip the decorative emoji from headings, bullets, status cells and code comments; the wording carries the warning, and the marks do not survive a terminal or a diff. - Join the soft-wrapped list items onto a single line each. Where a bullet carried more than a line's worth of detail, move the detail into the paragraph beside it instead of leaving a 380-character line. - Remove the fourth heading level: the four sub-object sections of the developer guide are now 5.8 to 5.11, and DFU, persistence, read-only properties and licensing move to 5.12 to 5.15. The two README links follow. - State what each document is and who it is for in its first sentence: field troubleshooting and the examples index only described their own layout. - State the working directory for the install and example commands. Every list item now fits within the 130-column limit in .markdownlint.json, so the two rules do not conflict. Verified: 656 passed, 2 skipped, and a scan of all eight files for emoji, fourth-level headings, soft-wrapped bullets and over-long lines reports nothing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two things are missing from the documentation, and this PR fixes both.
The interfaces are undocumented.
Arm.joint_follow(merged in #14) andArm.license/Arm.activate(present since the direct-CDC rewrite, 3d962bb) had no entry in any of the eightdocuments.
docs/DEVELOPER_GUIDE.md§4 tells the reader which entry points deliberately returnno
Msgenvelope;license()was missing from that list too.The documents had never been audited against the documentation rules. §4 of
AGENTS.mdentered the standard in #6 (fed097a), while the eight documents were rewritten in #2 — so the
rules that now govern them were written after them.
Changes
Interface documentation:
joint_followin guide §5.7 and in both READMEs. The notes come from the firmwaresource (litearm-stm32
master391e612, clean tree), not from the SDK alone: the payload is16N bytes with no
tau, the firmware clampsqto the soft limits andkp/kdto its MITlimits,
dqis a velocity reference rather than a rate limit, the accept path returns0x03/0x04/0x06, and the state frame keeps reportingMOVE_MIT_ALL, so the modefield does not tell the host that following is active.
license()among the entry points that return noMsgenvelope.Conformance to the §4 documentation rules:
carries the warning; the marks do not survive a terminal or a diff.
line's worth of detail, the detail moves into the paragraph beside it rather than staying as a
380-character line.
§5.8 to §5.11, and DFU, persistence, read-only properties and licensing move to §5.12 to
§5.15; the two README links follow.
the examples index only described their own layout.
Every list item now fits within the 130-column limit configured in
.markdownlint.json, so thestandard and the linter no longer conflict.
Testing
tests/test_doc_examples.pyparses everypythonblock in the eight documents, verifies eachsignature entry against
inspect.signature, and executes every example block against theoffline stub. The two blocks added here account for the two extra cases over the 654 that passed
before this work.
A separate scan of all eight files reports no emoji, no fourth-level heading, no soft-wrapped
list item and no line over 130 columns.
Issues
None — no issue tracks this.
Not in this PR
them would rewrite roughly 190 lines with no change in content, so it is left out.
src/litearm/testing.py) sends0x08through its catch-allelse: _ack,so the firmware's two new error codes for that command (
{0x08,0x01}short payload,{0x08,0x02}non-finite values) and its enable gate have no criterion anywhere; the coveragetest only asserts that the command id went out. Worth a separate change.