# 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 <method> <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 "<location> <method>", 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)<obj>, 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
  "<location> <method>" id exists, generate "(autodef)<location> <method>" 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).