From 24ca887ae428aabb66a2f92c04c545b6e5b70f1f Mon Sep 17 00:00:00 2001 From: Kinneyzhang Date: Mon, 31 Aug 2026 16:27:31 +0800 Subject: [PATCH] docs: clear final M0 checkdoc warnings --- etaf-compiler.el | 9 ++++++--- etaf-component.el | 2 +- etaf-runtime.el | 13 ++++++++----- etaf-view.el | 7 ++++--- 4 files changed, 19 insertions(+), 12 deletions(-) diff --git a/etaf-compiler.el b/etaf-compiler.el index aab3907..097162c 100644 --- a/etaf-compiler.el +++ b/etaf-compiler.el @@ -99,7 +99,8 @@ (defun etaf-compiler--compile-children (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) blocks) (while children @@ -141,7 +142,8 @@ (list blocks programs))) (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 ((or (null form) (stringp form)) (list (list :kind 'literal :value form :path path :static-p t) programs)) @@ -203,7 +205,8 @@ (cons static dynamic)))) (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) (etaf-compiler--compile-children (list form) nil nil (or slot-mode :projection))) diff --git a/etaf-component.el b/etaf-component.el index ec96c8c..a48b8b2 100644 --- a/etaf-component.el +++ b/etaf-component.el @@ -95,7 +95,7 @@ A defined setup may return nil; setup presence is tracked independently." (unless (and (eq etaf--component-phase 'render) etaf--current-component-instance) (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 (etaf--component-definition-error "Current Component does not declare :setup")) diff --git a/etaf-runtime.el b/etaf-runtime.el index e615d6d..f8c1c38 100644 --- a/etaf-runtime.el +++ b/etaf-runtime.el @@ -3200,7 +3200,8 @@ each logical item." (defun etaf--runtime-keyed-range-metadata (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 (let ((items (plist-get snapshot :items)) (snapshot-keys (etaf--runtime-keyed-range-keys expr snapshot)) @@ -3240,7 +3241,7 @@ each logical item." (defun etaf--runtime-index-range-item-identities (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) (let ((semantic (gethash semantic-id @@ -5069,7 +5070,7 @@ the range is not eligible for keyed incremental rendering." (defun etaf--runtime-range-direct-node-signature (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. Nested Range identity is retained, but its internal artifact is deliberately 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 (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 (etaf--semantic-backend-range-item-root-ids old) (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))))) (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 changed. If its root identity/cardinality and direct payload are stable, its staged artifact differs solely because it contains a descendant candidate; diff --git a/etaf-view.el b/etaf-view.el index 42a12c4..7748c3b 100644 --- a/etaf-view.el +++ b/etaf-view.el @@ -293,7 +293,8 @@ Component semantics. COMPONENT-NAME labels diagnostics." result)) (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)) (spec (etaf--component-call-spec call)) (declared (mapcar #'etaf--component-prop-key @@ -536,7 +537,7 @@ belong to the anonymous `default' slot." children)))) (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." (let ((arms nil) (remaining rest) @@ -650,7 +651,7 @@ Return `(COMPILED . REMAINING)' for one compiler-owned Range program." :range-item ,item-renderer))))) (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) (while children (let* ((form (car children))