Prompt
Add docstrings to functions and comments to explain complex logic, especially when the purpose or reasoning isn’t immediately clear from the code itself. This includes documenting function parameters, explaining non-obvious conditions, and clarifying implementation decisions or workarounds.
Functions should have docstrings that explain their purpose and parameters:
(defn convert-index
"Converts a numeric index to different formats based on delta value.
Args:
idx - numeric index to convert
delta - format selector (0=numeric, 1=letters, else=roman)"
[idx delta]
(cond
(zero? delta) idx
(= delta 1) (some-> (util/convert-to-letters idx) util/safe-lower-case)
:else (util/convert-to-roman idx)))
Complex conditions and workarounds should be explained with comments:
;; hovering on page ref in page-preview does not show another page-preview
;; if {:preview? true} was passed to page-blocks-cp
(page-reference false page {:preview? true} nil)
;; Check if edit input exists to prevent navigation when not editing
(not (state/get-edit-input-id))
Configuration options should include clear explanations and usage examples, especially for potentially risky settings or complex features.