twincat-comment-enforcer

name	twincat-comment-enforcer
description	Enforce TE1030-compliant documentation comments whenever TwinCAT 3 source files are created or modified. Use when Codex edits .TcPOU, .TcGVL, .TcDUT, methods, interfaces, or declarations and must ensure the final code includes TE1030-ready summary, description, and param comments instead of leaving documentation as an afterthought.

TwinCAT Comment Enforcer

Overview

Use this skill to make TE1030 documentation comments part of the definition of done for TwinCAT code changes. It complements code-writing and build-fixing skills by ensuring changed code is also documented correctly.

Read references/enforcement-checklist.md for the final review checklist. Read references/comment-coverage-rules.md for which TwinCAT elements must receive TE1030 comments after a change.

Enforcement Rule

When TwinCAT source is added or modified, do not stop after the code builds. Before considering the task complete, ensure the changed code has appropriate TE1030 documentation comments.

What must be documented

Document newly added or materially changed:

• PROGRAM
• FUNCTION_BLOCK
• FUNCTION
• methods
• interfaces
• major DUTs and enums
• non-obvious VAR_INPUT, VAR_OUTPUT, and important internal declarations

If a code element is touched only for a trivial formatting change, do not force a full documentation rewrite.

Required TE1030 minimum

For most TwinCAT code changes, the minimum acceptable documentation is:

• one @summary for the main changed code element
• @param comments for non-obvious inputs/outputs or declarations
• a description block if behavior, sequencing, modes, alarms, or assumptions are not obvious

Use the more detailed TE1030 markup rules from $twincat-te1030-comments when writing the comments. Write the comment body primarily in Traditional Chinese, keeping only established technical terms in English when needed for precision.

Decision heuristics

Add or update documentation when:

• behavior changed
• new commands, modes, alarms, or states were introduced
• an FB interface changed
• a declaration became important for external users or maintainers
• the code now has semantics that a future reader could misread without guidance

Documentation can stay minimal when:

• the change is purely mechanical
• only whitespace or formatting changed
• the code element already has accurate TE1030 comments and the behavior did not change

Completion checklist

Before finishing a TwinCAT coding task, check:

1. Does the changed code element have a TE1030 @summary?
2. Do non-obvious inputs, outputs, or declarations have @param comments?
3. If mode logic, timing, alarms, or command semantics changed, is there a description block?
4. Are generated-documentation comments using //! or (*! ... *), not plain //?
5. If VS2022 build-fix workflow was used, were the TE1030 comments added before the final rebuild?

Relationship to other skills

• Use $twincat-te1030-comments for the concrete markup syntax and templates.
• Use $twincat-build-fixer when code changes must also build cleanly in VS2022.
• Use $twincat-code-reader when you first need to understand the code before documenting it.

Typical requests this skill should handle

• "Whenever you edit TwinCAT code, also add TE1030 comments."
• "Make documentation enforcement part of the TwinCAT workflow."
• "Do not leave new FBs undocumented."
• "Before finishing, ensure modified TwinCAT code has proper TE1030 comments."