punkshell/goals/G-052-oo-method-autodef.md

G-052 TclOO method-level autodef documentation

Status: proposed Scope: src/modules/punk/ns-999999.0a1.0.tm (generate_autodef oo branches, cmd_traverse), src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test Goal: an undocumented method on a tcl::oo object or class gets an (autodef) punk::args definition generated from its introspected parameter list (info object call + method definition arglists - the machinery generate_autodef already uses for its class summary), so 'i $obj <args...>' shows method-level usage with good/bad argument marking instead of only the class summary with the method word highlighted - explicitly documented methods continue to win. Acceptance: the cmdhelp_GAP_oo_undocumented_method_class_summary_only pin flips: cmdinfo on an undocumented method resolves a method-level (autodef) docid with the trailing words in args_remaining, and bogus trailing arguments render error-scheme output instead of an info-scheme class summary; documented-method behaviour (cmdhelp_oo_documented_method) is unchanged; instance methods, class-defined methods and mixin/superclass-inherited methods resolve (constructor/'new' signatures at minimum characterized, in-scope or explicitly deferred in the detail file); the "-choiceprefix 0 ... methods must be specified in full always? - review" question on the class-summary method choicelist is resolved and documented either way; cmdflow.test and cmdhelp.test pass.

Context

For a tcl::oo object, generate_autodef builds a class-summary (autodef) definition: a method leader whose choices are the public methods, with choiceinfo doctype markers (objectmethod/classmethod/coremethod) and subhelp links for methods that have explicit punk::args docs (the id convention is " ", e.g. "::punk::ansi::class::class_ansi rendertest"). A documented method therefore resolves and renders with full argument marking.

An UNDOCUMENTED method does not: 'i $obj checksum' shows only the class summary with the method word highlighted, and because the class-summary definition ends with @values -unnamed true, ANY trailing words parse successfully - 'i $obj checksum bogus1 bogus2' renders an info-scheme (all good) class summary. Pinned 2026-07-10: cmdhelp_GAP_oo_undocumented_method_class_summary_only (cmdtype ooobject, docid (autodef), args_remaining carries the method + bogus words, info scheme + goodarg on the method row).

TclOO is fully introspectable: info object call $obj $method locates the implementation, and info class definition $class $method / info object definition yield the parameter list. generate_autodef already walks info object call for the choiceinfo markers, and already has a partial single-method arglist path (the oodef switch handling 1/2-element parameter entries, defaults, and trailing 'args') - it is just not wired up as a general method-level (autodef) generation step in the doc walk.

Approach

• When cmd_traverse consumes a method word on an oo object/class and no explicit " " id exists, generate "(autodef) " from the introspected parameter list (same element mapping as the existing proc autodef: name / {name default} / trailing args -> -multiple 1 -optional 1) and resolve to it, leaving subsequent words as args_remaining for parse marking.
• Location follows the same rules as the existing choiceinfo id convention (object-local methods keyed by the object, class methods by the class, inherited by the defining class) so explicit docs and autodefs share the lookup key.
• Decide and document the class-summary -choiceprefix 0 question ("methods must be specified in full always? - review" at the method choicelist): whatever the answer, parse and doc walk must agree (G-040 parity).
• Constructor/'new' on classes: characterize at minimum; generating an autodef from info class constructor is the natural extension - explicitly defer if not landed.

Notes

• punk::ansi::class::class_ansi (rendertest / render_to_input_line) is the documented- method reference pattern; the fixture in cmdhelp.test mirrors it (HelpClass docmeth documented, plainmeth undocumented).
• Filters, private methods and unknown handlers are marked in choiceinfo today but out of scope for autodef generation.
• Coordinate the cmdtype reported for method resolutions with G-051's doconly decision.
• Archived-goal references in this file: G-040 achieved 2026-07-08 (goals/archive/G-040-punkargs-choicealiases.md).