Function parameter documentation

[bbb651]

Currently function parameters cannot have documentation. This feels like pretty arbitrary restriction (which might be biased, even if not intentionally, from rust not supporting it? It is a very requested feature there: https://github.com/rust-lang/rust/issues/57525).

Different languages have different structured way to embed per-parameter documentation in the function documentation: Swift:

/// - Parameters:
///   - food: The food for the sloth to eat.
///   - quantity: The quantity of the food for the sloth to eat.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {

C#:

public class Point
{
    /// <summary>
    /// This method changes the point's location to
    /// the given coordinates.
    /// </summary>
    /// <param name="xPosition">the new x-coordinate.</param>
    /// <param name="yPosition">the new y-coordinate.</param>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
}

Java:

/**
* Returns an Image object that can then be painted on the screen. 
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument. 
* <p>
* This method always returns immediately, whether or not the 
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives 
* that draw the image will incrementally paint on the screen. 
*
* @param  url  an absolute URL giving the base location of the image
* @param  name the location of the image, relative to the url argument
* @return      the image at the specified URL
* @see         Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}

Doxygen (and a different \param style):

/**
 * A brief history of JavaDoc-style (C-style) comments.
 *
 * This is the typical JavaDoc-style C-style comment. It starts with two
 * asterisks.
 *
 * @param theory Even if there is only one possible unified theory. it is just a
 *               set of rules and equations.
 */
void cstyle( int theory );

and many more. When generating bindings for these languages, per-parameter documentation gives us the information to properly embed it in the function documentation, or generate parameter doc-comment in languages that support it (I'm not aware of any).

My use case is generating WIT interfaces for wayland (client side, for server side the situation is the same with requests and events swapped), where I map requests to function and events to variant cases. For both each argument has a name, type and summary, I want the summary for the function arguments to be properly displayed regardless of the target language.

Maybe this should apply to return types as well? They too often have a special doc-comment syntax in languages, I feel like it somewhat depends on #356 (Does a doc-comment without a name make sense? Or maybe it makes sense as a replacement for the name?)

[lukewagner]

Thanks for filing and it's exciting to hear you're working on WIT interfaces for wayland! I think having support for naming parameters and results names makes a lot of sense. @lann even brought this up earlier in #256 but I think we busy at the time so it fell through the cracks.

One question I have (and probably had the first time too) is how much structure we want to impose on doc comments once @ annotations get involved. E.g., is there any form of lexical, syntactic or semantic validation that kicks in for lines with @? I'm not too familiar with what all these other existing doc-comment systems do and what the norms are here, so I'd be curious to hear from anyone that is.

Also, @lann, is there any structure in the documentation custom section to speak of?

[bbb651]

Sorry if I was unclear, I was suggesting allowing doc-comment on parameters:

create_buffer: func(
    /// buffer to create
    id: new_id,
    /// buffer byte offset within the pool
    offset: s32,
    /// buffer width, in pixels
    width: s32,
    /// buffer height, in pixels
    height: s32,
    /// number of bytes from the beginning of one row to the beginning of the next row
    stride: s32,
    /// buffer pixel format
    format: u32
);

It's exactly to avoid annotation syntax in doc-comment as much as possible, as they are harder to parse (all binding generators must parse and reemit them regardless, having them named @param is only superficial, they all have slightly different syntax around whitespace) and more error prone (Looking at #256, what happens if a dash is used instead of a hyphen-minus, or other types or amount of whitespace characters are used? IIUC it's not part of the WIT syntax so it won't be an outright syntax error, so it creates discrepancies and incompatibilities between different tools).

[lukewagner]

Ahh, that does seem like a nice simple alternative; sounds good to me! Anyone else have thoughts on this?

[lann]

It uses up more vertical space for long parameter lists (2 lines per param) and "looks weird" (I don't recall seeing it as a convention anywhere else), but those are both pretty weak arguments.

Thoughts on documenting the return value?