Move docstring spec-refs into # comments#206
Merged
Merged
Conversation
Relocate spec citations (section references, proposal numbers, and "the spec" attributions) out of Python docstrings into # comments across src/ and tests/, so docstrings describe behavior and the adjacent comments carry the spec provenance. Extends the per-PR docstring fixes from 0059b and 0060a into a full codebase sweep. Scope: only spec citations move. Bare capitalized RFC-2119 contract words (MUST / MAY) stay in docstrings as behavioral contract language, matching the establishing cleanup in #169. The added # comments reproduce the citations; nothing is deleted, only relocated. No behavior change.
There was a problem hiding this comment.
Pull request overview
Moves spec provenance out of Python docstrings and into adjacent # comments across core runtime and tests, keeping docstrings focused on behavior while preserving traceable citations for spec conformance.
Changes:
- Relocated spec section/proposal citations from docstrings into nearby
#comments insrc/openarmature/*. - Applied the same docstring/citation separation sweep across conformance, integration, and unit tests.
- Light docstring rewording to keep sentences grammatical after citation removal.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/openarmature/graph/events.py | Removes spec section markers from event docstrings; keeps provenance in comments. |
| src/openarmature/graph/parallel_branches.py | Moves pipeline-utilities/observability spec refs out of docstrings into comments for branch dispatch behavior. |
| src/openarmature/observability/llm_event.py | Shifts tool-call serialization spec citation from docstring to comment. |
| src/openarmature/observability/langfuse/client.py | Moves Langfuse session/user spec citation out of docstring into method-body comments; clarifies tool observation comment. |
| src/openarmature/observability/langfuse/observer.py | Relocates tool-observation proposal citation from docstring into a comment. |
| src/openarmature/observability/otel/observer.py | Removes spec references from multiple docstrings; adds/adjusts nearby comments to retain spec provenance. |
| tests/conformance/adapter.py | Moves parallel-branches proposal/section citations out of helper docstrings into comments. |
| tests/conformance/harness/directives.py | Moves directive proposal citations out of schema docstrings into comments. |
| tests/integration/test_langfuse_sdk_adapter.py | Moves proposal/section citations out of test docstring into a comment above the test. |
| tests/unit/test_tool_call.py | Moves proposal citation out of module docstring into a top-level comment. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+252
to
+254
| # Spec proposal 0064 §8.4.1: trace(session_id=, user_id=) populates the live | ||
| # Trace's sessionId / userId grouping. proposal 0020 (sessions capability) will | ||
| # later supply openarmature.session_id along the same passthrough. |
Comment on lines
1629
to
+1631
| message. ``arguments`` / ``result`` are payload, gated by | ||
| ``disable_provider_payload`` (§5.5.4) + the §5.5.5 truncation | ||
| contract. The OA-namespace ``openarmature.tool.*`` attributes | ||
| ``disable_provider_payload`` and truncated. The OA-namespace | ||
| ``openarmature.tool.*`` attributes |
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.
Relocates spec citations out of Python docstrings into
#comments acrosssrc/andtests/, so docstrings describe behavior and the adjacent comments carry the spec provenance. Extends the per-PR docstring fixes made in 0059b and 0060a into a full codebase sweep.Scope (Option A)
Only spec citations move:
§section references,proposal NNNN, and "the spec ..." attributions. Bare capitalized RFC-2119 contract words (MUST/MAY, e.g. "the input list MUST NOT be mutated") stay in docstrings as behavioral contract language, matching the precedent set by the establishing cleanup in #169. The added#comments reproduce the citations; nothing is deleted, only relocated. No behavior change.Files (10)
graph/events.py,graph/parallel_branches.py,observability/llm_event.py,observability/langfuse/client.py,observability/langfuse/observer.py,observability/otel/observer.py,tests/conformance/adapter.py,tests/conformance/harness/directives.py,tests/integration/test_langfuse_sdk_adapter.py,tests/unit/test_tool_call.pyValidation
src/+tests/