WebAssembly / WebAssembly/component-model

Function parameter documentation

Open
#533 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
WebAssembly
Stars
1.4k
Forks
130
Avg merge
2d 1h
Merged PRs (30d)
15

Description

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?)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No source files or tests are identified; start by reading the component-model documentation and the discussion around #356. Done would be an agreed representation for per-parameter documentation, including how it supports WIT interface and binding generation, with the return-type question resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
wasm
Domain
backend-api-design, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.