docs: add comment for HelpGen field and example for WithHelpGen

Author: steverusso

builder.go

@@ -329,6 +329,8 @@ func (in InputInfo) Default(v string) InputInfo {
 	return in
 }
 
+// WithHelpGen sets the HelpGen field of this input. See the HelpGen field
+// documentation on [InputInfo] to learn more about how it is used.
 func (in InputInfo) WithHelpGen(hg HelpGenerator) InputInfo {
 	in.HelpGen = hg
 	return in

cli.go

@@ -134,6 +134,12 @@ type InputInfo struct {
 	ValueName   string
 	ValueParser ValueParser
 
+	// If an input is encountered during parsing that has either HelpGen or Versioner
+	// set, the parser will return HelpOrVersionRequested with whatever either of those
+	// functions return as the Msg. See CommandInfo.ParseThese to learn more.
+	//
+	// Note: adding an input that has HelpGen set to a CommandInfo will prevent this
+	// library from automatically adding the DefaultHelpInput to that command.
 	HelpGen   HelpGenerator
 	Versioner Versioner
 }
@@ -297,8 +303,11 @@ func (in *CommandInfo) Parse() (*Command, error) {
 // involves setting the Path field of this command and all subcommands, as well as
 // ensuring there are no logical errors in the structure of this command (such as a
 // command containing duplicate option names). This method will panic if there are any
-// structural errors in this CommandInfo. Assuming a clean structure, this method then
-// parses input against this CommandInfo using args as the command line arguments.
+// schema errors in this CommandInfo.
+//
+// Assuming a clean schema, this method then parses input against this CommandInfo using
+// args as the command line arguments. If there is a help or version input found on any
+// command level, this function will return a [HelpOrVersionRequested] error.
 func (in *CommandInfo) ParseThese(args ...string) (*Command, error) {
 	if !in.isPrepped {
 		in.prepareAndValidate()

examples_test.go

@@ -494,6 +494,27 @@ func ExampleInputInfo_ShortOnly() {
 	// cli.test: unknown option '--flag'
 }
 
+func ExampleInputInfo_WithHelpGen() {
+	in := cli.New("example").
+		Help("an example program").
+		Opt(cli.NewOpt("a")).
+		Opt(cli.NewOpt("b")).
+		Opt(cli.NewBoolOpt("h").
+			Help("will show a custom help message").
+			WithHelpGen(func(o cli.Input, c *cli.CommandInfo) string {
+				return "totally custom help message\n" +
+					"use data on the provided CommandInfo to form a custom help message\n" +
+					fmt.Sprintf("for example, this command has %d options including this one", len(c.Opts))
+			}))
+
+	_, err := in.ParseThese("-h")
+	fmt.Println(err)
+	// Output:
+	// totally custom help message
+	// use data on the provided CommandInfo to form a custom help message
+	// for example, this command has 3 options including this one
+}
+
 func ExampleInputInfo_WithParser() {
 	// This is a horrible parsing function for coordinates.
 	// It's just for example purposes.