How to present function comments?

Toit

#How to present function comments?

Thread channel in help

Arubinu 05/01/2025 01:35 PM

I'd like to clarify how the functions/methods work, but I don't see anything official.

Did I miss it?

Example:

/**
 * @fn float ** merci(int*, double**,char*,int)
 * @param   \b param1 
 * @param   \b param2
 * @param   \b param3
 * @param   \b param4
 * @brief   votre briefing concernant la fonction
 * @details  les détails de la fonction
 * @return  ce qu'elle retourne
 */

(edited)

bitphlipphar 05/01/2025 01:38 PM

Take a look at https://docs.toit.io/language/sdk/toitdoc and let us know what kind of guidance is missing!

bitphlipphar 05/01/2025 01:39 PM

You can refer to parameters using $param1, etc.

bitphlipphar 05/01/2025 01:41 PM

We typically write more prose with less rigid structure, so we would usually try to explain what the method does and returns in words - referring to the specific parameters in the text.

Arubinu 05/01/2025 01:42 PM

I see, because I noticed that the suggestions for functions when using them are very basic. You constantly have to go and consult the definition.

bitphlipphar 05/01/2025 01:42 PM

That's good feedback, thanks.

Arubinu 05/01/2025 01:43 PM

Optional parameters can be displayed with "--" but that's about it.
Thank you for taking the time to answer all these questions ^^

Arubinu 05/01/2025 01:45 PM

I'm not comfortable with all this in other languages. I admit that for me it would be enough for the editor to display the function definition with the comment preceding it.

OPArubinu

I see, because I noticed that the suggestions for functions when using them are very basic. You constantly have to go and consult the definition.

floitsch 05/01/2025 01:49 PM

That's a limitation of the LSP server. It's on my to-do list, but not yet on the top

9 messages in total