annotate-source-files

Annotate Source Files

Add PUT workflow annotations to source files so putior can extract structured workflow data and generate Mermaid diagrams.

When to Use

• After analyzing a codebase with analyze-codebase-workflow and having an annotation plan
• Adding workflow documentation to new or existing source files
• Enriching auto-detected workflows with manual labels and connections
• Documenting data pipelines, ETL processes, or multi-step computations

Inputs

• Required: Source files to annotate
• Required: Annotation plan or knowledge of the workflow steps
• Optional: Style preference: single-line or multiline (default: single-line)
• Optional: Whether to use put_generate() for skeleton generation (default: yes)

Procedure

Step 1: Determine Comment Prefix

Each language has a specific comment prefix for PUT annotations. Use get_comment_prefix() to find the correct one.

library(putior)

# Common prefixes
get_comment_prefix("R")    # "#"
get_comment_prefix("py")   # "#"
get_comment_prefix("sql")  # "--"
get_comment_prefix("js")   # "//"
get_comment_prefix("ts")   # "//"
get_comment_prefix("go")   # "//"
get_comment_prefix("rs")   # "//"
get_comment_prefix("m")    # "%"
get_comment_prefix("lua")  # "--"

Got: A string like "#", "--", "//", or "%".

Line and block comments: putior detects annotations in both line comments (//, #, --) and C-style block comments (/* */, /** */). For JS/TS, both // and /* */ blocks are scanned. Python triple-quote strings (''' ''') are not detected — use # for Python annotations.

If fail: If the extension is not recognized, the file language may not be supported. Check get_supported_extensions() for the full list. For unsupported languages, use # as a conventional default.

Step 2: Generate Annotation Skeletons

Use put_generate() to create annotation templates based on auto-detected I/O.

# Print suggestions to console
put_generate("./src/etl/")

# Single-line style (default)
put_generate("./src/etl/", style = "single")

# Multiline style for complex annotations
put_generate("./src/etl/", style = "multiline")

# Copy to clipboard for pasting
put_generate("./src/etl/", output = "clipboard")