influxdata
query: flux functions and arguments should have documentation that is programmatically accessible
Motivation: supporting code completion is nice, but for a richer, more user-friendly Flux experience, there should be a way to programmatically access help for functions and their arguments. Moreover, this should be usable for automatically generating static documentation for the Flux language.
For example, if I have typed from(db: "mydb") |> r, completion should tell me that range is a valid function, but there should also be a way to see a short documentation blurb for range, like "range excludes data whose timestamp is not inside the provided bounds".
After I have decided to use the range function and typed from(db: "mydb") |> range(, I should be able to see documentation for the individual arguments, like "setting start will exclude data whose timestamp is earlier than the value of start" and "setting end will exclude data whose timestamp is later than the value of end".
In consideration of user-defined imports later on, it is important that user-defined functions can have their own programmatically-accessible documentation.
For the REPL, it may be worth defining a help builtin so that I can write help(range) to interactively read the help for the range function and its arguments.
The UI is manually keeping track of updates to Flux and updating the docs in the product. We would love to have this data served from the flux library itself so it is kept up to date.
Proposal for a first pass is to move functions list and the manual updates process to the flux team vs. the UX team.
what's left on this issue now that we have https://github.com/influxdata/flux-lsp ?