stewbeet.plugins.auto.headers
The auto.headers plugin automatically generates documentation headers for mcfunction files.
It analyzes function calls, function tags, advancement rewards, and macro function arguments
to create @within documentation that shows which functions, tags, or advancements
call each function, providing clear dependency tracking and usage documentation.
Context Analysis: The plugin extracts and preserves execution contexts
from execute commands (such as as @e, positioned, at, rotated, facing, etc.)
and automatically determines the execution context for functions based on their callers.
Macro Analysis: For macro functions (using $(variable) syntax), the plugin automatically
detects macro variables, infers their types from function calls and storage NBT data, and generates
@args documentation with type information. It supports both direct NBT calls and storage-based calls,
with type inheritance from calling functions.
Source Code: stewbeet/plugins/auto/headers/__init__.py
Source Code: stewbeet/plugins/auto/headers/object.py
Source Code: stewbeet/plugins/auto/headers/context_analyzer.py
Source Code: stewbeet/plugins/auto/headers/execution_parser.py
Source Code: stewbeet/plugins/auto/headers/function_analyzer.py
Source Code: stewbeet/plugins/auto/headers/macro_analyzer.py
Source Code: stewbeet/plugins/auto/headers/macro_parser.py
Source Code: stewbeet/plugins/auto/headers/type_inference.py
What it does
- Automatically generates function documentation headers
- Tracks function call relationships and dependencies
- Analyzes function tag memberships and usage
- Monitors advancement reward function calls
- Detects macro variables and infers their types automatically
- Generates
@argsdocumentation for macro functions with type information - Type inference from NBT data, direct calls, and storage operations
- Type inheritance from calling functions via
$(variable)references - Preserves manual descriptions in
@argswhile auto-filling missing types - Extracts execution contexts from
executecommands (as,at,positioned,rotated,facing,in,anchored,align) - Determines function execution contexts automatically based on caller analysis
- Creates
@withinand@argsdocumentation
Dependencies
- โ Required: Beet context with functions, function tags, and advancements
- ๐ Position: Should run after all content generation but before finalization
- ๐ง Optional: Existing function headers (will be parsed and updated)
Some Features Showcase
Example of a function being called by multiple functions with macro arguments:
Example of a function being called by multiple functions with different contexts:
Example of a function being called by multiple macro arguments (with arguments types):
Configuration
Basic Example Configuration
pipeline:
- ...
- stewbeet.plugins.auto.headers
- ... # Some finalization plugins
# No configuration required - plugin runs automatically
# Processes all functions, function tags, and advancements by defaultConfiguration Options
| Option | Type | Default | Description |
|---|---|---|---|
| Header Generation | automatic | Enabled | Creates headers for all mcfunction files |
| Dependency Tracking | automatic | Enabled | Analyzes function calls and references |
| Tag Analysis | automatic | Enabled | Processes function tag memberships |
| Advancement Rewards | automatic | Enabled | Tracks advancement reward functions |
Features
Macro Argument Analysis (NEW!)
Automatically detects and types macro function arguments:
- ๐ Auto-detection - Scans function content for
$(variable)patterns - ๐ Type inference from NBT - Analyzes direct calls like
function test {x:10,y:20.5f,id:"hello"} - ๐พ Storage-based inference - Parses
data modify storagecommands to extract types - ๐ Type inheritance - When
$(var)references another function's argument, inherits the type - ๐งฌ Recursive analysis - Follows function call chains to ensure all types are resolved
- ๐ Description preservation - Keeps manually written descriptions while filling missing types
- ๐ฏ NBT type mapping - Correctly identifies byte(b), short(s), int, long(l), float(f), double(d), string, compound, list
- ๐ Order preservation - Arguments listed in order of first appearance in the file
- ๐ Merge logic - Combines inferred types with manual annotations (manual takes precedence)
Supported Type Inference Patterns:
# Direct NBT call
function namespace:target {x:10,y:20.5f,name:"Player"}
# -> Infers: x (int), y (float), name (string)
# Storage-based call
data modify storage temp:data macro set value {dimension:"minecraft:overworld",x:0,y:64,z:0}
function namespace:teleport with storage temp:data macro
# -> Infers: dimension (string), x (int), y (int), z (int)
# Type inheritance
function caller {result:$(value)}
# If caller has @args with value (int), target inherits: result (int)Execution Context Analysis
Analyses and determines execution contexts:
- ๐ Parses
executecommands to extract contexts likeas @e[type=zombie],positioned ~ ~1 ~,at @s,rotated 45 0 - ๐ง Smart selector simplification for complex selectors with NBT data and multiple attributes
- ๐ Context inheritance - functions inherit execution contexts from their callers when appropriate
- ๐ Automatic context determination for advancement reward functions (
as the player & at current position) - โก Special handling for tick/load tags and other built-in contexts
- ๐ Context preservation in
@executedheader sections
Function Header Parsing
Parses existing function headers:
- ๐ Detects
#> function_nameheader format - ๐ Extracts existing
@withininformation - ๐ Preserves custom documentation comments
- ๐ Separates header content from actual function code
Function Tag Analysis
Analyzes function tag memberships for documentation:
- ๐ Processes all function tags in the datapack
- ๐ Creates
#namespace:tag_namereferences for tagged functions - ๐ Handles both string and object-based tag entries
- โ Supports conditional tag entries with IDs
Advancement Reward Tracking
Monitors advancement reward function calls:
- ๐ฏ Scans advancement reward sections for function calls
- ๐ Creates
advancement namespace:advancement_namereferences - ๐ Links reward functions to their triggering advancements
- โ Ensures proper advancement-to-function relationship tracking
Function Call Analysis
Analyzes direct function calls within mcfunction files:
- ๐ Scans each line for
functioncommands - ๐ฏ Extracts called function names with quote handling
- ๐ง Captures macro parameters and scheduling information
- ๐งฉ Resolves macro placeholders in the called path (
$function ns:types/$(type)) against every function - ๐ท๏ธ Lists a quoted function id given as data (
{give_function:"ns:give/weapon"}) as astring inreference - ๐ฎ Analyzes execution contexts from
executecommands (as @e,positioned,at,rotated,facing,in,anchored,align) - ๐ Parses complex selectors with NBT data and multiple attributes
- ๐ Inherits execution contexts from calling functions when appropriate
- ๐ Prevents duplicate entries in the
@withinlist
Dialog and Enchantment Analysis
Reads functions named in dialogs (run_command actions) and enchantments (run_function effects):
- ๐ Creates
dialog namespace:pathandenchantment namespace:pathreferences
Header Generation System
Generates documentation headers:
- ๐ Creates standardized
#> function_nameheaders - ๐ Generates
@withinsections listing all callers - ๐ Writes
(public)instead of???on an uncalled function of the project outside itsns:v<version>/folder - ๐ง Preserves existing custom documentation
- โ Uses proper formatting with tabs and spacing
File Writing and Updates
Updates all mcfunction files with generated headers:
- ๐ Writes updated headers to all processed functions
- ๐ Overwrites existing files with new documentation
- ๐ Maintains clean formatting and structure
- โ Ensures all functions have complete documentation headers
Next steps
- Writing functions and files: the functions this plugin post-processes.
- All plugins: the rest of the pipeline, in the order it runs.
- Configuring the build: enabling, ordering and configuring plugins.