provide command line info on plugins

[rogpeppe]

It would be nice to be able to list the available plugins from the command line
and find out information on individual plugins, including the expected
function signature.

[awalterschulze]

Sounds easy enough to emit a list, but the function signature depends on the input parameters. How would the user provide these on the command line?

[rogpeppe]

I'd just document it like:

The copy plugin generates a function of the form:

      func deriveCopy(dst, src T)

  for some type T, which copies the contents of src into dst.
  T must be a pointer or a map. Its contents are copied according to
  the following rules: .... etc

[awalterschulze]

May I ask why, since there are already godocs and examples available on github.
Is this for some type of integration?

[rogpeppe]

I'd prefer not to go to github every time I wonder what plugins are available or when I'm wondering what a particular plugin does (in the same way that I often use "go doc" rather than going online to the Go documentation). Also, I'm not always online.

The help for a given plugin could just copy some of the package doc comment from github.com/awalterschulze/goderive/plugin/$pluginname and print that, I guess, to
avoid too much textual duplication.

[awalterschulze]

Interesting.

Ok so then how would that be different than running:

go doc ./plugin/fmap

Or

go doc github.com/awalterschulze/goderive/plugin/fmap

[rogpeppe]

Not that much, apart from the fact that:

• a user of goderive shouldn't need to know the canonical import path of goderive. Someone may have forked goderive and added more plugins, for example, or tweaked existing plugins.
• the package declaration, the first paragraph of the package doc comment, and the information on the New function, are all irrelevant to the goderive user.
• the user might not even have the goderive package installed, as they might have installed the command directly as a binary.

Note that the user will almost never be in the goderive root directory, so your first suggestion probably won't work most of the time.

[awalterschulze]

Good points.

Ok so for example fmap I would get a godoc like this

$ go doc github.com/awalterschulze/goderive/plugin/fmap
package fmap // import "github.com/awalterschulze/goderive/plugin/fmap"

Package fmap contains the implementation of the fmap plugin, which generates
the deriveFmap function.

The deriveFmap function applies a given function to each element of a list,
returning a list of results in the same order.

    deriveFmap(func(A) B, []A) []B
    deriveFmap(func(rune) B, string) []B

deriveFmap can also be applied to a function that returns a value and an
error.

    deriveFmap(func(A) B, func() (A, error)) (B, error)
    deriveFmap(func(A) (B, error), func() (A, error)) (func() (B, error), error)
    deriveFmap(func(A), func() (A, error)) error
    deriveFmap(func(A) (B, c, d, ...), func() (A, error)) (func() (B, c, d, ...), error)

deriveFmap will propogate the error and not apply the first function to the
result of the second function, if the second function returns an error.

func New(typesMap derive.TypesMap, p derive.Printer, deps map[string]derive.Dependency) derive.Generator
func NewPlugin() derive.Plugin

[awalterschulze]

But we would prefer

$ goderive doc fmap

The deriveFmap function applies a given function to each element of a list,
returning a list of results in the same order.

    deriveFmap(func(A) B, []A) []B
    deriveFmap(func(rune) B, string) []B

deriveFmap can also be applied to a function that returns a value and an
error.

    deriveFmap(func(A) B, func() (A, error)) (B, error)
    deriveFmap(func(A) (B, error), func() (A, error)) (func() (B, error), error)
    deriveFmap(func(A), func() (A, error)) error
    deriveFmap(func(A) (B, c, d, ...), func() (A, error)) (func() (B, c, d, ...), error)

deriveFmap will propogate the error and not apply the first function to the
result of the second function, if the second function returns an error.

[awalterschulze]

If so then we could generate this doc from the godoc as you suggested and avoid more duplication of documentation.
What do you think?

[rogpeppe]

Yes, this looks nice.
I think I'd suggest naming the subcommand "help" rather than "doc".
Then we could have:

 goderive help (or --help):
     show information on command line flags and the available subcommands
 goderive help fmap
     show information on a particular command.
 goderive list
     show a brief description of each plugin (one line for each so it's greppable)

This has a potential ambiguity issue if the stdlib ever adds "help" or "list" packages, but I think we can be safe that even if they do, noone will actually want to run goderive on them :-)

[awalterschulze]

I think list should also take into account the pluginprefixes and print out a list of plugin name : prefix : first line of goderive help

fmap : deriveFmap : The deriveFmap function applies a given function to each element of a list, returning a list of results in the same order.

What do you think?

[rogpeppe]

Perhaps. That seems a little verbose though. I suspect it might be nicer if each plugin provided a single line summary:

 fmap: map a function onto a list

It might be nice to be able to get list to show the function signatures too, similarly to how the godoc page for a package shows the function signatures at the top.

[awalterschulze]

Is this acceptable?

goderive --list
    show a brief description of each plugin (one line for each so it's greppable
goderive --doc=fmap
    show information on a particular command.

where doc is the print out we discussed before.
and --list becomes

$ goderive --list
...
equal: deriveEqual: checks for the equality of two values
fmap : deriveFmap : map a function onto a list.
...

So that we can also have:

$ goderive --list --pluginprefix="fmap=m"
...
equal: deriveEqual: checks for the equality of two values
fmap : m : map a function onto a list.
...