mirror of
https://github.com/Z3Prover/z3
synced 2026-03-17 02:30:01 +00:00
89 lines
4.5 KiB
Python
89 lines
4.5 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Add godoc comments to Z3 Go bindings systematically.
|
|
This script adds proper godoc documentation to all exported types and functions.
|
|
"""
|
|
|
|
import os
|
|
import re
|
|
|
|
# Godoc comment templates for common patterns
|
|
TYPE_COMMENTS = {
|
|
'Config': '// Config represents a Z3 configuration object used to customize solver behavior.\n// Create with NewConfig and configure using SetParamValue before creating a Context.',
|
|
'Context': '// Context represents a Z3 logical context.\n// All Z3 objects (sorts, expressions, solvers) are tied to the context that created them.\n// Contexts are not thread-safe - use separate contexts for concurrent operations.',
|
|
'Symbol': '// Symbol represents a Z3 symbol, which can be either a string or integer identifier.\n// Symbols are used to name sorts, constants, and functions.',
|
|
'AST': '// AST represents an Abstract Syntax Tree node in Z3.\n// This is the base type for all Z3 expressions, sorts, and function declarations.',
|
|
'Sort': '// Sort represents a type in Z3\'s type system.\n// Common sorts include Bool, Int, Real, BitVec, Array, and user-defined datatypes.',
|
|
'Expr': '// Expr represents a Z3 expression (term).\n// Expressions are typed AST nodes that can be evaluated, simplified, or used in constraints.',
|
|
'FuncDecl': '// FuncDecl represents a function declaration in Z3.\n// Function declarations define the signature (domain and range sorts) of functions.',
|
|
'Pattern': '// Pattern represents a pattern for quantifier instantiation.\n// Patterns guide Z3\'s E-matching algorithm for quantifier instantiation.',
|
|
'Quantifier': '// Quantifier represents a quantified formula (forall or exists).\n// Quantifiers bind variables and include optional patterns for instantiation.',
|
|
'Lambda': '// Lambda represents a lambda expression (anonymous function).\n// Lambda expressions can be used as array values or in higher-order reasoning.',
|
|
'Statistics': '// Statistics holds performance and diagnostic information from Z3 solvers.\n// Use GetKey, GetUintValue, and GetDoubleValue to access individual statistics.',
|
|
}
|
|
|
|
FUNCTION_COMMENTS = {
|
|
'NewConfig': '// NewConfig creates a new Z3 configuration object.\n// Use SetParamValue to configure parameters before creating a context.',
|
|
'NewContext': '// NewContext creates a new Z3 context with default configuration.\n// The context manages memory for all Z3 objects and must outlive any objects it creates.',
|
|
'NewContextWithConfig': '// NewContextWithConfig creates a new Z3 context with the given configuration.\n// The configuration is consumed and should not be reused.',
|
|
}
|
|
|
|
def add_godoc_comment(content, pattern, comment):
|
|
"""Add godoc comment before a type or function declaration."""
|
|
# Check if comment already exists
|
|
lines = content.split('\n')
|
|
result = []
|
|
i = 0
|
|
|
|
while i < len(lines):
|
|
line = lines[i]
|
|
|
|
# Check if this line matches our pattern
|
|
if re.match(pattern, line):
|
|
# Check if previous line is already a comment
|
|
if i > 0 and (result[-1].strip().startswith('//') or result[-1].strip().startswith('/*')):
|
|
# Comment exists, skip
|
|
result.append(line)
|
|
else:
|
|
# Add comment
|
|
result.append(comment)
|
|
result.append(line)
|
|
else:
|
|
result.append(line)
|
|
|
|
i += 1
|
|
|
|
return '\n'.join(result)
|
|
|
|
def process_file(filepath, type_comments, func_comments):
|
|
"""Process a single Go file and add godoc comments."""
|
|
print(f"Processing {filepath}...")
|
|
|
|
with open(filepath, 'r', encoding='utf-8') as f:
|
|
content = f.read()
|
|
|
|
# Add type comments
|
|
for type_name, comment in type_comments.items():
|
|
pattern = f'^type {type_name} struct'
|
|
content = add_godoc_comment(content, pattern, comment)
|
|
|
|
# Add function comments
|
|
for func_name, comment in func_comments.items():
|
|
pattern = f'^func (\\([^)]+\\) )?{func_name}\\('
|
|
content = add_godoc_comment(content, pattern, comment)
|
|
|
|
with open(filepath, 'w', encoding='utf-8') as f:
|
|
f.write(content)
|
|
|
|
print(f"Updated {filepath}")
|
|
|
|
if __name__ == '__main__':
|
|
go_api_dir = os.path.dirname(os.path.abspath(__file__))
|
|
|
|
# Process z3.go with core types
|
|
z3_go = os.path.join(go_api_dir, 'z3.go')
|
|
if os.path.exists(z3_go):
|
|
process_file(z3_go, TYPE_COMMENTS, FUNCTION_COMMENTS)
|
|
|
|
print("\nGodoc comments added successfully!")
|
|
print("Run 'go doc' to verify documentation.")
|