Merge pull request urfave#2119 from dearchap/cleanup_docs_04272025_2

Add docs for advanced value source

Author: dearchap

docs/v3/examples/arguments/advanced.md

@@ -7,8 +7,8 @@ search:
 
 The [Basics] showed how to access arguments for a command. They are all retrieved as strings which is fine
 but it we need to say get integers or timestamps the user would have to convert from string to desired type. 
-To ease the burden on users the `cli` library offers predefined <Type>Arg and <Type>Args structure to faciliate this
-The value of the argument can be retrieved using the command.<Type>Arg() function. For e.g
+To ease the burden on users the `cli` library offers predefined `{Type}Arg` and `{Type}Args` structure to faciliate this
+The value of the argument can be retrieved using the `command.{Type}Arg()` function. For e.g
 
 <!-- {
   "args" : ["10"],
@@ -52,7 +52,7 @@ $ greet 10
 We got 10
 ```
 
-Instead of using the cmd.XXXArg() function to retrieve the argument value a destination for the argument can be set
+Instead of using the `cmd.{Type}Arg()` function to retrieve the argument value a destination for the argument can be set
 for e.g
 
 <!-- {
@@ -152,9 +152,9 @@ func main() {
 
 Some things to note about multi value arguments
 
-1. They have XXXArgs type instead of XXXArg to differentiate them from single value arguments
-2. The Max field needs to be defined to a non zero value without which it cannot be parsed
-3. Max field value needs to be greater then the Min field value
+1. They are of `{Type}Args` type rather than `{Type}Arg` to differentiate them from single value arguments
+2. The `Max` field needs to be defined to a non zero value without which it cannot be parsed
+3. `Max` field value needs to be greater than the `Min` field value
 
 As with single value args the destination field can be set
 
@@ -214,11 +214,11 @@ Following multi value arguments are supported
 - `TimestampArgs`
 
 It goes without saying that the chain of arguments set in the Arguments slice need to be consistent. Generally a glob
-argument(max=-1) should be set for the argument at the end of the slice. To glob args we arent interested in we coud add
+argument(`max=-1`) should be set for the argument at the end of the slice. To glob args we arent interested in we coud add
 the following to the end of the Arguments slice and retrieve them as a slice
 
 ```
-	&StringArgs{
-		Max: -1,
-	},
+&StringArgs{
+	Max: -1,
+},
 ```

docs/v3/examples/flags/basics.md

@@ -153,7 +153,7 @@ The following basic flags are supported
 - `StringFlag`
 - `TimestampFlag`
 
-For full list of flags see https://pkg.go.dev/github.com/urfave/cli/v3
+For full list of flags see [`https://pkg.go.dev/github.com/urfave/cli/v3`](https://pkg.go.dev/github.com/urfave/cli/v3)
 
 ### Timestamp Flag ###
 

docs/v3/examples/flags/value-sources.md

@@ -7,17 +7,19 @@ search:
 
 Flags can have their default values set from different sources. The following sources are
 provided by default with `urfave/cli`
+
  - Environment
  - Text Files
 
 The library also provides a framework for users to plugin their own implementation of value sources
 to be fetched via other mechanisms(http and so on). 
 
 In addition there is a `urfave/cli-altsrc` repo which hosts some common value sources to read 
+from files or via http/https. 
+
  - YAML
  - JSON
  - TOML
-from files or via http/https. 
 
 #### Values from the Environment
 
@@ -136,78 +138,85 @@ Note that default values are set in the same order as they are defined in the
 
 #### Values from alternate input sources (YAML, TOML, and others)
 
-There is a separate package altsrc that adds support for getting flag values
+There is a separate package [altsrc](https://github.com/urfave/cli-altsrc) that adds support for getting flag values
 from other file input sources.
 
-Currently supported input source formats:
+Currently supported input source formats by that library are:
 
 - YAML
 - JSON
 - TOML
 
-In order to get values for a flag from an alternate input source the following
-code would be added to wrap an existing cli.Flag like below:
+A simple straight forward usage would be
 
 ```go
-  // --- >8 ---
-  altsrc.NewIntFlag(&cli.IntFlag{Name: "test"})
-```
+package main
 
-Initialization must also occur for these flags. Below is an example initializing
-getting data from a yaml file below.
+import (
+	"log"
+	"os"
+	"context"
 
-```go
-  // --- >8 ---
-  command.Before = func(ctx context.Context, cmd *Command) (context.Context, error) {
-	return ctx, altsrc.InitInputSourceWithContext(command.Flags, NewYamlSourceFromFlagFunc("load"))
-  }
-```
+	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli-altsrc/v3"
+)
 
-The code above will use the "load" string as a flag name to get the file name of
-a yaml file from the cli.Context.  It will then use that file name to initialize
-the yaml input source for any flags that are defined on that command.  As a note
-the "load" flag used would also have to be defined on the command flags in order
-for this code snippet to work.
+func main() {
+	cmd := &cli.Command{
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:    "password",
+				Aliases: []string{"p"},
+				Usage:   "password for the mysql database",
+				Sources: altsrc.YAML("somekey", altsrc.StringSourcer("/path/to/filename")),
+			},
+		},
+	}
 
-Currently only YAML, JSON, and TOML files are supported but developers can add
-support for other input sources by implementing the altsrc.InputSourceContext
-for their given sources.
+	if err := cmd.Run(context.Background(), os.Args); err != nil {
+		log.Fatal(err)
+	}
+}
+```
 
-Here is a more complete sample of a command using YAML support:
+Sometime the source name is itself provided by another CLI flag. To allow the library to "lazy-load"
+the file when needed we use the `altsrc.NewStringPtrSourcer` function to bind the value of the flag 
+to a pointer that is set as a destination of another flag
 
-<!-- {
-  "args": ["&#45;&#45;help"],
-  "output": "&#45&#45;test int.*default: 0"
-} -->
 ```go
 package main
 
 import (
-	"context"
-	"fmt"
+	"log"
 	"os"
+	"context"
 
-	altsrc "github.com/urfave/cli-altsrc/v3"
 	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli-altsrc/v3"
 )
 
 func main() {
-	flags := []cli.Flag{
-		&cli.IntFlag{
-			Name:    "test",
-			Sources: altsrc.YAML("key", "/path/to/file"),
-		},
-		&cli.StringFlag{Name: "load"},
-	}
-
+	var filename string
 	cmd := &cli.Command{
-		Action: func(context.Context, *cli.Command) error {
-			fmt.Println("--test value.*default: 0")
-			return nil
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:        "file",
+				Aliases:     []string{"f"},
+				Value:       "/path/to/default",
+				Usage:       "filename for mysql database",
+				Destination: &filename,
+			},
+			&cli.StringFlag{
+				Name:    "password",
+				Aliases: []string{"p"},
+				Usage:   "password for the mysql database",
+				Sources: altsrc.YAML("somekey", altsrc.NewStringPtrSourcer(&filename)),
+			},
 		},
-		Flags: flags,
 	}
 
-	cmd.Run(context.Background(), os.Args)
+	if err := cmd.Run(context.Background(), os.Args); err != nil {
+		log.Fatal(err)
+	}
 }
-```
+```