How to use a multi-line comment for a function?


#1

I am making a library project with several modules. I can successfully build the project, test the project, and build the documentation. However, I can’t seem to make multi-line doc comments for non-container entities. Multi-line comments work for modules - e.g.:

/*!
Module.
Line 1 is shown.

Line 2 is properly shown.
*/

...

The above example works correctly. However, trying to do something like that for a function only shows the first line - e.g.:

/**
Function.
Line 1 is shown.

Line 2 is not shown.
*/
pub fn foo() {
}

Anything beyond the first line doesn’t show up in the docs. I’ve tried different indent levels and prefixing each line with *, but nothing works. I also can’t find much/any documentation on multi-line doc strings, and I haven’t found an example of multi-line doc strings for functions.

Anyone have any advice?


#2

The simplest solution would be to prefix every line with ///.
The following should work:

///Function.
///Line 1 is shown.
///
///Line 2 is not shown.
pub fn foo() {
}

I don’t know of any way to make a doc-comment explicitly multi-line. But since you were fine with prefixing everything with * I think this should work for you.


#3

This doesn’t work either :frowning: only the first line is shown. Thanks though!


#4

Did you try clicking on the function in question (in your example foo)? This is an example from the standard library. Look at the atomics. Only a one line summary is shown until you click on it. Then more information comes up.

Prefixing with /// really should work, as it is the way the standard library is documented. You can see an example of the source code here.


#5

Oh my god - I didn’t realize that multi-line comments only show up when you click it! Thank you SO much!