docs: clear final M0 checkdoc warnings

This commit is contained in:
Kinneyzhang 2026-08-31 16:27:31 +08:00
parent 525e6b38b7
commit 24ca887ae4
4 changed files with 19 additions and 12 deletions

View File

@ -99,7 +99,8 @@
(defun etaf-compiler--compile-children (defun etaf-compiler--compile-children
(children path programs slot-mode) (children path programs slot-mode)
"Compile sibling CHILDREN below PATH with directive grouping." "Compile sibling CHILDREN below PATH, extending PROGRAMS.
SLOT-MODE selects ordinary projection or slot compilation."
(let ((child-index 0) (let ((child-index 0)
blocks) blocks)
(while children (while children
@ -141,7 +142,8 @@
(list blocks programs))) (list blocks programs)))
(defun etaf-compiler--compile-block (form path programs slot-mode) (defun etaf-compiler--compile-block (form path programs slot-mode)
"Compile View FORM at PATH, returning `(BLOCK PROGRAMS)' or nil." "Compile View FORM at PATH using PROGRAMS and SLOT-MODE.
Return `(BLOCK PROGRAMS)' or nil."
(cond (cond
((or (null form) (stringp form)) ((or (null form) (stringp form))
(list (list :kind 'literal :value form :path path :static-p t) programs)) (list (list :kind 'literal :value form :path path :static-p t) programs))
@ -203,7 +205,8 @@
(cons static dynamic)))) (cons static dynamic))))
(defun etaf-compiler--compile (form &optional slot-mode) (defun etaf-compiler--compile (form &optional slot-mode)
"Compile FORM into `(BLUEPRINT PROGRAM-CODE...)', or return nil." "Compile FORM under optional SLOT-MODE into a View blueprint.
Return `(BLUEPRINT PROGRAM-CODE...)', or nil."
(pcase-let* ((`(,roots ,programs) (pcase-let* ((`(,roots ,programs)
(etaf-compiler--compile-children (etaf-compiler--compile-children
(list form) nil nil (or slot-mode :projection))) (list form) nil nil (or slot-mode :projection)))

View File

@ -95,7 +95,7 @@ A defined setup may return nil; setup presence is tracked independently."
(unless (and (eq etaf--component-phase 'render) (unless (and (eq etaf--component-phase 'render)
etaf--current-component-instance) etaf--current-component-instance)
(etaf--component-definition-error (etaf--component-definition-error
"etaf-state is available only during Component view/render")) "ETAF state is available only during Component view/render"))
(unless etaf--current-component-setup-defined-p (unless etaf--current-component-setup-defined-p
(etaf--component-definition-error (etaf--component-definition-error
"Current Component does not declare :setup")) "Current Component does not declare :setup"))

View File

@ -3200,7 +3200,8 @@ each logical item."
(defun etaf--runtime-keyed-range-metadata (defun etaf--runtime-keyed-range-metadata
(expr snapshot item-root-groups item-node-counts) (expr snapshot item-root-groups item-node-counts)
"Return retained metadata for EXPR SNAPSHOT and aligned item spans." "Return retained metadata for EXPR and SNAPSHOT.
ITEM-ROOT-GROUPS and ITEM-NODE-COUNTS describe aligned item spans."
(when snapshot (when snapshot
(let ((items (plist-get snapshot :items)) (let ((items (plist-get snapshot :items))
(snapshot-keys (etaf--runtime-keyed-range-keys expr snapshot)) (snapshot-keys (etaf--runtime-keyed-range-keys expr snapshot))
@ -3240,7 +3241,7 @@ each logical item."
(defun etaf--runtime-index-range-item-identities (defun etaf--runtime-index-range-item-identities
(runtime semantic-ids identity-index) (runtime semantic-ids identity-index)
"Validate SEMANTIC-IDS and index their Host identities in IDENTITY-INDEX." "Validate RUNTIME SEMANTIC-IDS and index Hosts in IDENTITY-INDEX."
(dolist (semantic-id semantic-ids) (dolist (semantic-id semantic-ids)
(let ((semantic (let ((semantic
(gethash semantic-id (gethash semantic-id
@ -5069,7 +5070,7 @@ the range is not eligible for keyed incremental rendering."
(defun etaf--runtime-range-direct-node-signature (defun etaf--runtime-range-direct-node-signature
(runtime generation semantic-id candidate-p) (runtime generation semantic-id candidate-p)
"Return SEMANTIC-ID's direct material signature. "Return SEMANTIC-ID's direct material signature in RUNTIME.
When CANDIDATE-P is non-nil, read the candidate overlay before GENERATION. When CANDIDATE-P is non-nil, read the candidate overlay before GENERATION.
Nested Range identity is retained, but its internal artifact is deliberately Nested Range identity is retained, but its internal artifact is deliberately
excluded so descendant-only work cannot masquerade as an ancestor change." excluded so descendant-only work cannot masquerade as an ancestor change."
@ -5118,7 +5119,8 @@ excluded so descendant-only work cannot masquerade as an ancestor change."
(defun etaf--runtime-range-direct-payload-equal-p (defun etaf--runtime-range-direct-payload-equal-p
(runtime generation old candidate) (runtime generation old candidate)
"Return whether OLD and CANDIDATE own the same direct Range payload." "Return whether OLD and CANDIDATE own the same direct Range payload.
RUNTIME and GENERATION provide committed and candidate node signatures."
(and (equal (and (equal
(etaf--semantic-backend-range-item-root-ids old) (etaf--semantic-backend-range-item-root-ids old)
(etaf--semantic-backend-range-item-root-ids candidate)) (etaf--semantic-backend-range-item-root-ids candidate))
@ -5135,7 +5137,8 @@ excluded so descendant-only work cannot masquerade as an ancestor change."
(etaf--semantic-backend-range-item-root-ids candidate))))) (etaf--semantic-backend-range-item-root-ids candidate)))))
(defun etaf--runtime-normalize-range-changes (runtime generation changes) (defun etaf--runtime-normalize-range-changes (runtime generation changes)
"Return non-overlapping CHANGES ordered as originally staged. "Normalize RUNTIME CHANGES against GENERATION in staged order.
Return a non-overlapping change list.
An ancestor absorbs descendants only when its own direct material payload An ancestor absorbs descendants only when its own direct material payload
changed. If its root identity/cardinality and direct payload are stable, its changed. If its root identity/cardinality and direct payload are stable, its
staged artifact differs solely because it contains a descendant candidate; staged artifact differs solely because it contains a descendant candidate;

View File

@ -293,7 +293,8 @@ Component semantics. COMPONENT-NAME labels diagnostics."
result)) result))
(defun etaf--forward-component-attrs (call attrs component-name) (defun etaf--forward-component-attrs (call attrs component-name)
"Return copied root Component CALL receiving caller ATTRS." "Return copied root Component CALL receiving caller ATTRS.
COMPONENT-NAME identifies the forwarding owner for diagnostics."
(let* ((copy (copy-sequence call)) (let* ((copy (copy-sequence call))
(spec (etaf--component-call-spec call)) (spec (etaf--component-call-spec call))
(declared (mapcar #'etaf--component-prop-key (declared (mapcar #'etaf--component-prop-key
@ -536,7 +537,7 @@ belong to the anonymous `default' slot."
children)))) children))))
(defun etaf--compile-branch-children (first rest slot-mode) (defun etaf--compile-branch-children (first rest slot-mode)
"Compile branch FIRST and adjacent arms from REST. "Compile branch FIRST and adjacent arms from REST under SLOT-MODE.
Return `(COMPILED . REMAINING)' for one compiler-owned Range program." Return `(COMPILED . REMAINING)' for one compiler-owned Range program."
(let ((arms nil) (let ((arms nil)
(remaining rest) (remaining rest)
@ -650,7 +651,7 @@ Return `(COMPILED . REMAINING)' for one compiler-owned Range program."
:range-item ,item-renderer))))) :range-item ,item-renderer)))))
(defun etaf--compile-child-sequence (children slot-mode) (defun etaf--compile-child-sequence (children slot-mode)
"Compile sibling CHILDREN with branch and keyed-list structure." "Compile sibling CHILDREN with branch and keyed-list SLOT-MODE structure."
(let (compiled) (let (compiled)
(while children (while children
(let* ((form (car children)) (let* ((form (car children))