Functions documentation

[JTKU]

Hello,
I'm currently trying to write a very light LSP for vrl, and it made me notice that most of the functions don't have a summary and usage to display.
I'd like to make a PR to add these to all the existing functions, so I was wondering how to format them and what to include in their content.

For the summary, something close to the function description in the VRL function reference should fit most of the time, or just its first sentence when it's too long?

For the usage, I assume using the whole function description could work.
However, should the function properties (fallibility, purity, errors to handle) and the description of its arguments be present as well?
Currently, for the few functions with a usage, it contains more or less the same as the summary plus the name of its arguments inserted in the description. Sometimes, some more information is added, or the description of its arguments.
Do you have any requirements about it? Otherwise, I'll likely go with something like that:

[purity][fallibility]

<full description>

<arguments description>

<errors to handle>

Thanks in advance!

[pront]

Hi @JTKU, I am not sure I am following.

Let's take https://vector.dev/docs/reference/vrl/functions/#from_unix_timestamp for example. There is a summary here:

...and for usage, we have the [examples] section.(https://vector.dev/docs/reference/vrl/functions/#from_unix_timestamp)

Can you give me an example to help me understand better the proposed changes? Thank you.

[JTKU]

Sorry that wasn't clear!

The vector docs has all the information indeed, but the crate does not seem to have it.

As an example with the abs function:
https://github.com/vectordotdev/vrl/blob/main/src%2Fstdlib%2Fabs.rs#L18-L49

For the Function trait, it does not define summary and usage, so when trying to get these info from a Node to print them out, I only get a "TODO".

This is the case for most functions.

I assumed the best way to get this information was to "copy" the vector docs for each function into the vrl crate to stop getting "TODO"s.

My initial question is basically : I'd like to complete the functions documentation inside of the vrl crate, is this the right way? And if it is, what format should be used to have a coherent description format across all functions?

I hope this makes it clearer.

[pront]

Ah yes, this makes sense! This will also help with #280 (ideally we want to generate the .cue files from the VRL source code)

Feel free to send a test PR to see and we can take it from there.