| name | twincat-te1030-comments |
| description | Write and rewrite TwinCAT 3 source-code comments so they comply with TE1030 TwinCAT 3 Documentation Generation markup rules. Use when Codex edits .TcPOU, .TcGVL, .TcDUT, or related TwinCAT source and the resulting comments must be valid for TE1030 documentation output, including summary, description, example, param, note, image, cross-reference, and audience markups. |
TwinCAT TE1030 Comments
Overview
Use this skill whenever TwinCAT comments are meant to become generated documentation, not just inline developer notes. Prefer TE1030-valid documentation comments over ad hoc prose.
Read references/te1030-markup-rules.md for the markup catalog and placement rules. Read references/te1030-comment-templates.md for practical templates you can reuse for PROGRAM, FUNCTION_BLOCK, methods, variables, and parameter descriptions.
Core Rules
1. Use TE1030 delimiters only for generated documentation
Allowed documentation comment delimiters:
//! for single-line documentation comments(*! ... *) for multi-line documentation comments
Do not assume ordinary // comments are included in generated documentation. Treat normal comments as internal developer notes unless the user explicitly wants both.
2. Prefer @summary and @param as the default abbreviated form
Use abbreviated one-line tags where possible:
//! @summary ...//! @description ...//! @param variableName ...//! @code ...//! @preliminary ...
Use normal XML-style tags when:
- the content spans multiple lines
- nested markup is needed
- the markup has no abbreviated form
- readability would suffer in one line
3. Always distinguish generated docs from internal comments
TE1030 examples make this distinction explicit:
//! ... or (*! ... *) becomes generated documentation- ordinary
// ... remains an internal code comment
Do not convert every internal comment into TE1030 markup. Use TE1030 only for information that belongs in generated documentation.
4. Respect markup hierarchy
description, summary, and example are top-level documentation sections. Many other markups are only valid inside them.
Put these inside description, summary, or example:
- headings such as
<h1> to <h6>
<code><literal>- lists and tables
- cross references like
$SomeElement
<see> and <seealso><note type="..."><image uri="..."><audience type="..."><preliminary>
@param stands alone and does not need to be wrapped in description, summary, or example.
5. Keep one coherent summary per code element
TE1030 only outputs one summary per POU. Write one clear summary block near the top of the code element instead of scattering many summary comments.
6. Use @param for declarations when trailing comments are not enough
Use @param when:
- the declaration line is too crowded
- the explanation is longer than a short inline note
- you want parameter documentation grouped in one place
7. Write comments that are documentation-ready
Prefer:
- what the element is for
- what the caller/user should know
- command/feedback semantics
- mode behavior
- timeout and alarm meaning
- assumptions and constraints
Avoid:
- repeating obvious type names
- narrating every assignment
- mixing generated documentation with transient debugging notes
Default Comment Style For This Workspace
Unless the user asks otherwise:
- write comments primarily in Traditional Chinese
- keep established technical terms in English only when translation would reduce clarity or conflict with TwinCAT terminology
- add one
@summary for each public PROGRAM, FUNCTION_BLOCK, FUNCTION, method, interface, or major DUT
- add
@param comments for non-obvious inputs, outputs, and important internal declarations
- use
description blocks for behavior, sequencing, and mode semantics
- use
example only when usage is genuinely clarified by a code sample
- keep internal
// comments for implementation-only notes
Typical requests this skill should handle
- "Rewrite this TwinCAT comment to follow TE1030."
- "Add documentation comments to this function block."
- "Document this POU so TE1030 can generate proper output."
- "Convert these inline notes into valid
@summary and @param markup."
- "Standardize our TwinCAT comments for Documentation Generation."
