Cli: conflict between godoc document and github manual document

[acheron2302]

In godoc subcommand example, the subcommand code is:

Subcommands: []*Command{
                {
                    Name:        "english",
                    Aliases:     []string{"en"},
                    Usage:       "sends a greeting in english",
                    Description: "greets someone in english",
                    Flags: []Flag{
                        &StringFlag{
                            Name:  "name",
                            Value: "Bob",
                            Usage: "Name of the person to greet",
                        },
                    },
                    Action: func(c *Context) error {
                        fmt.Println("Hello,", c.String("name"))
                        return nil
                    },
                },
            },

but in the github subcommand example, the subcommand type is:

Subcommands: []cli.Command{
        {
          Name:  "add",
          Usage: "add a new template",
          Action: func(c *cli.Context) error {
            fmt.Println("new task template: ", c.Args().First())
            return nil
          },
        },
        {
          Name:  "remove",
          Usage: "remove an existing template",
          Action: func(c *cli.Context) error {
            fmt.Println("removed task template: ", c.Args().First())
            return nil
          },
        },

As you can see the godoc Subcommand's type is []*Commands but in the github manual, the godoc Subcommand's type is []Commands.

This is just an example but there are also many type that's different.

My question is why are godoc and github document so different from each other? And which document should i follow?

[lynncyrin]

@acheron2302 offhand, I don't know what godoc is using to generate its documentation. If you wanted to investigate how exactly that pipeline works, I could help you out.

In the meantime, building off of the above, we only actively maintain the github manual. So the github manual is what you should be using.

[rliebz]

The godoc is generated from the tests and uses the default code branch, which is master. It's run alongside the test suite in the pipeline, so it should always be up to date as long as the build is passing.

This is a link to that test case:

https://github.com/urfave/cli/blob/ee9b3fc7d13f866db38bd32f67f5081df22c3cac/app_test.go#L55-L92

The GitHub URL there is for v1, the equivalent link is here, which should match the godoc: https://github.com/urfave/cli/blob/master/docs/v2/manual.md#subcommands

You should only consult the v1 docs if you're using v1, and the latest if you're on v2.