feat(doc): add doc command (wip)

[jfbus]

This is a wip command to generate a mermaid flowchart from a FSM.

The final command might be different, this command is for evaluation purposes.

TODO

• Event/State flowchart
• Call/Check/NotCheck
• add title
• title override as //fsm: comment
• style override as //fsm: comment
• strip prefix (e.g. StateXXX/EventXXX)
• edit Markdown file
• use cobra ?
• go generate
• doc

[Bluebugs]

This is a cool idea. I am unable to try the result. I get the following errors when trying on my own code:

panic: interface conversion: ast.Expr is *ast.SelectorExpr, not *ast.Ident

goroutine 1 [running]:
main.main()
	/home/cedric/work/fyne-labs/fsm/cmd/doc.go:107 +0x810

and

panic: runtime error: index out of range [1] with length 1

goroutine 1 [running]:
main.main()
	/home/cedric/work/fyne-labs/fsm/cmd/doc.go:108 +0x7fa

I just did a quick try, I will see if I can look at it a bit more later and see why it does that, but maybe you will have an idea.

[jfbus]

The crash should have been fixed (you probably assigned the fsm to a struct var, and my test data only assigned to local or global vars). The code would probably generate a wrong flowchart if 2 fsms are stored in the same struct, I'll try to fix it.

[jfbus]

As far as output is concerned, we could :

• doc [go file] [go file] : dumps all flowcharts to stdout
• doc [go file] [go file] -o [markdown file] : adds/replaces the flowchart to a markdown file

When scanning a markdown file, we could look for the flowchart name and add/replace the mermaid block below. The flowchart name is currently either [package name].[func name]() or [package name].[global var name] depending where fsm.New() is called. File and line numbers could be added.

[jfbus]

We could also add //fsm: comments to change the flowchart name or add comments to the mermaid flowchart (not sure about this, this could clutter the output).

[Bluebugs]

Ok, this is working now. Pretty cool. I like the idea of using //fsm: comment to set the title and maybe additional information for the mermaid graph (specifying the prefix to remove there would be nice too).

The way I would plan to use this tool is part of a go generate command and enforce that if run during our PR github action, no change are triggered. This way we will have always up to date documentation. That might influence how you think about the command line and if you need something like cobra.

The only bit in my previous PR that could be of interest to you is how the in place replacement for the graph was done, but that's not really a complex things. So if you are ok with that, I will close that PR.