DocumentFunction.jl

applypatch!(patch)

Apply a DocPatch atomically after verifying that the source file still has the hash captured when the patch was created.

Arguments

• patch: Source-hash-protected documentation edit to apply.

Returns

true after the updated source file is written successfully.

checkdocs(path; public_only=true, require_parameters=false, state_path="", module_name="")

Return deterministic, offline documentation issues for scanned functions.

When .documentfunction.toml exists, source hashes accepted by a previous review are also checked so changed implementations are reported as stale.

Arguments

• path: Julia source file or directory to inspect.

Keywords

• public_only: Whether to check only exported, declared-public, or explicitly documented functions.
• require_parameters: Whether every extracted argument and keyword must have a structured description.
• state_path: Documentation inventory path, or an empty string to use the project default.
• module_name: Module prefix to use instead of the nearest project name.

Returns

A vector of DocumentationIssue records in deterministic source order.

docpatch(draft; replace_existing=false, allow_unreviewed=false, allow_content_loss=false)

Create a source-hash-protected edit that inserts a static docstring or replaces the existing attached documentation expression.

Set replace_existing=true explicitly when replacing existing documentation. By default, drafts containing unresolved prose or unverified examples are rejected; set allow_unreviewed=true only to create an explicitly provisional patch for manual review. Replacing existing prose requires allow_content_loss=true because structured drafts cannot prove that every intentional paragraph is represented.

Arguments

• draft: Documentation draft and source metadata used to create the edit.

Keywords

• replace_existing: Whether an already attached documentation expression may be replaced.
• allow_unreviewed: Whether a draft for which needsreview is true may be patched.
• allow_content_loss: Whether an existing documentation expression may lose prose not represented by the draft.

Returns

A DocPatch containing the byte range, replacement, and original file hash.

documentationcontext(spec; root="", evidence_paths=String[], max_callsites=8)

Produce a deterministic evidence bundle for a human or coding agent to turn into semantic Julia documentation.

The bundle includes source-defined signatures, defaults, candidate prose, existing documentation, implementation text, and matching calls from supplied test, example, or documentation paths.

Arguments

• spec: Structured function metadata to describe.

Keywords

• root: Repository root used to render relative evidence paths.
• evidence_paths: Test, example, or documentation files and directories to search for representative calls.
• max_callsites: Maximum number of matching call-site lines to include.

Returns

A Markdown evidence bundle suitable for human or coding-agent review.

documentfunction(f::Function; location=true, maintext="", argtext=Dict(), keytext=Dict())

Render legacy Markdown describing the methods, positional arguments, and keywords of f.

Arguments

• f: Function whose runtime methods are inspected.

Keywords

• location: Whether to include runtime-derived source locations in the Markdown.
• maintext: Optional prose shown before the method list.
• argtext: Descriptions keyed by exact positional-argument name strings.
• keytext: Descriptions keyed by exact keyword name strings.

Returns

A newline-terminated Markdown string.

Notes

This compatibility API uses runtime reflection and does not retain keyword types, defaults, or requiredness; new documentation should use scanfunctions and static docstrings.

draftdocumentation(spec; summary="", argtext=Dict(), keytext=Dict(), returntext="", example_values=Dict(), example_method=1)

Build an offline, reviewable documentation draft from extracted facts, caller-provided descriptions, existing prose, and conservative templates.

Name- or type-derived prose is marked needs_review; unresolved semantics are rendered as explicit TODO items rather than invented descriptions.

Arguments

• spec: Structured function metadata from scanfunctions or functionspec.

Keywords

• summary: Evidence-backed function summary supplied by the caller.
• argtext: Positional-argument descriptions keyed by Symbol or String names.
• keytext: Keyword descriptions keyed by Symbol or String names.
• returntext: Evidence-backed description of the return value.
• example_values: Julia source expressions used to resolve example arguments.
• example_method: One-based source-method index used to construct the example.
• example_output: Expected example output, when known.
• example_verified: Whether the supplied example and output were already executed and validated.

Returns

A DocumentationDraft whose inferred fields retain confidence, provenance, evidence, and review status.

exampledraft(spec; values=Dict(), include_optional_keywords=false, method_index=1)

Create a conservative call example for one source method.

The result is a template, not a verified execution, unless the caller supplies verified=true after executing it in the target project.

Arguments

• spec: Structured function metadata used to construct the call.

Keywords

• values: Julia source expressions keyed by argument or keyword name.
• include_optional_keywords: Whether optional keywords should appear with their source defaults.
• method_index: One-based source-method index used to construct the call.
• output: Expected textual output, when known.
• verified: Whether the caller has already executed and validated the supplied example.

Returns

An ExampleDraft recording the code, unresolved placeholders, provenance, and verification state.

formatissues(issues; root="")

Format documentation issues without exposing absolute paths by default.

Arguments

• issues: Documentation issues to format.

Keywords

• root: Root used to render source locations as relative paths, or an empty string to show basenames.

Returns

A newline-delimited diagnostic string.

functionspec(f)

Locate and statically inspect the source-defined methods of a loaded Julia function.

Use scanfunctions directly when the package should not be loaded or when inspecting callable objects and generated methods whose source binding cannot be identified reliably.

Arguments

• f: Loaded callable whose source-defined methods should be located.

Returns

A FunctionSpec containing the matching source definitions.

getfunctionarguments(f::Function)
getfunctionarguments(method_strings::AbstractVector{String})

Return unique legacy positional-argument fragments.

Arguments

• f: Function whose runtime methods are inspected with Julia reflection.
• m: Rendered method strings to parse on a best-effort basis.

Returns

A vector of argument strings in first-seen order.

Notes

The function overload omits positional varargs and does not preserve defaults. The string overload is a compatibility parser, not a complete Julia syntax parser; use scanfunctions for source-faithful metadata.

getfunctionkeywords(f::Function)
getfunctionkeywords(method_strings::AbstractVector{String})

Return unique legacy keyword names or fragments.

Arguments

• f: Function whose runtime methods are inspected with Julia reflection.
• m: Rendered method strings to parse on a best-effort basis.

Returns

A vector of keyword strings in first-seen order.

Notes

The function overload discards keyword types, defaults, and requiredness. The string overload may retain raw annotations or defaults and is not a complete Julia syntax parser; use scanfunctions for source-faithful metadata.

getfunctionmethods(f::Function)

Return sorted, unique rendered method strings for f.

Arguments

• f: Function whose runtime method table is inspected.

Returns

A vector of rendered method strings.

needsreview(draft)

Return true when any generated prose or example still needs semantic or execution review.

Arguments

• draft: Documentation draft to inspect.

Returns

true when any description needs review or any example remains unverified.

renderdocstring(draft; indentation="")

Render a static, escaped Julia triple-quoted docstring literal.

The returned source is suitable for review and insertion before a function definition; it does not perform any file writes.

Arguments

• draft: Reviewed or reviewable documentation content to render.

Keywords

• indentation: Whitespace prepended to every line after the opening delimiter.

Returns

An escaped Julia triple-quoted docstring literal.

renderdocumentation(draft)

Render a DocumentationDraft as Markdown suitable for a Julia docstring.

Arguments

• draft: Reviewed or reviewable documentation content to render.

Returns

Markdown containing signatures, descriptions, parameters, returns, and examples.

scan(path; kwargs...)

Alias for scanfunctions for concise authoring scripts.

Arguments

• path: Julia source file or directory to inspect.

Keywords

• kwargs: Keyword arguments forwarded to scanfunctions.

Returns

A vector of FunctionSpec records.

scanfunctions(path; public_only=false, module_name="")

Parse Julia source without loading the target package and return structured function, method, argument, keyword, default, return-annotation, visibility, documentation, and source-span metadata.

When path is a directory, all .jl files below it are scanned in stable lexicographic order. module_name defaults to the nearest Project.toml package name. Files that omit their enclosing module declaration are assigned this prefix; literal include nesting is not evaluated, so scan such an implementation file separately with its full enclosing module name when necessary.

Arguments

• path: Julia source file or directory to inspect.

Keywords

• public_only: Whether to return only exported, declared-public, or explicitly documented functions.
• module_name: Module prefix to use instead of the nearest project name.

Returns

A vector of FunctionSpec records grouped by qualified function name.

Examples

import DocumentFunction

specs = DocumentFunction.scanfunctions("src"; public_only=true)
all(spec -> !isempty(spec.methods), specs)

verifyexample(example; project=".", timeout_seconds=30, allow_unsafe=false)

Execute a complete example twice in fresh Julia processes with the target project, a temporary working directory, and a timeout.

Stochastic examples must set their own fixed seed in example.code.

Common file, network, process, package-management, environment, and dynamic evaluation operations detected by the preflight require allow_unsafe=true. The preflight is not a security sandbox, so only trusted example source should be executed. The returned example is marked verified only when both executions succeed, produce identical standard output without standard-error diagnostics, and match example.output when expected output was provided.

Arguments

• example: Complete example draft to execute.

Keywords

• project: Julia project used by each isolated subprocess.
• timeout_seconds: Maximum duration allowed for each of the two executions.
• allow_unsafe: Whether potentially mutating, networked, dynamic, or process-launching code may run.

Returns

An ExampleVerification containing the promoted example, reproducibility result, output, errors, and timeout state.

verifyexamples(draft; project=".", timeout_seconds=30, allow_unsafe=false)

Execute every complete example in a documentation draft twice and return a copy of the draft containing the promoted verification results.

Arguments

• draft: Documentation draft whose examples should be executed.

Keywords

• project: Julia project used by each isolated subprocess.
• timeout_seconds: Maximum duration allowed for each execution.
• allow_unsafe: Whether potentially mutating, networked, dynamic, or process-launching code may run.

Returns

A tuple containing the updated DocumentationDraft and each detailed ExampleVerification result.

writeinventory(path; output="", public_only=true, allow_incomplete=false, module_name="")

Write a deterministic TOML inventory of reviewed source hashes.

Run this only after reviewing generated prose and verifying applicable examples; CI can subsequently use checkdocs without AI or network access.

Arguments

• path: Julia source file or directory whose accepted hashes should be recorded.

Keywords

• output: Inventory destination, or an empty string to use .documentfunction.toml in the project root.
• public_only: Whether to inventory only exported, declared-public, or explicitly documented functions.
• allow_incomplete: Whether to record functions with missing documentation or unresolved TODO markers.
• module_name: Module prefix to use instead of the nearest project name.

Returns

The absolute path of the written inventory file.

Represent proposed prose together with its evidence and review status.

Represent a byte-addressed, source-hash-protected docstring edit.

Collect a reviewable documentation draft for a FunctionSpec.

Report one deterministic documentation coverage or freshness problem.

Represent a proposed Julia example.

complete means that no placeholder remains, while verified means that the example has actually been executed successfully by the authoring workflow.

Record the result of executing an example twice in isolated Julia processes.

Collect source metadata for all scanned methods of a Julia function.

existing_doc contains the literal documentation text when available and the unevaluated documentation expression otherwise.

Describe one source-defined method without evaluating the package.

Distinguish positional parameters from keyword parameters in source metadata.

Describe one positional or keyword parameter exactly as written in source.

type_text and default_text are syntax strings and are nothing when the source does not declare them.

Describe a byte-accurate span in a Julia source file.

path is used for editing and diagnostics, while rendered documentation uses repository-relative paths supplied by the caller.