bytecodealliance / bytecodealliance/wit-bindgen

Comments and Doc Comments not working as expected.

Open
#1,333 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
1.5k
Forks
286
Avg merge
6h 32m
Merged PRs (30d)
19

Description

Reading: https://component-model.bytecodealliance.org/design/wit.html#comments
I tried applying comments to my wit files, and documentation and generating markdown.
But they do not work as I would expect.

All comments are ending up in the markdown as documentation.

For example:

``` wit
package test:test;

/**
# Test Heading

And this is also test data.

## Something else

more test info.
*/

// This should not be in docs.

/* This also should not be in docs. */

/// Test World
world test {

/// A Bytes String
type bstr = list;

// 128 bit value - but shouldn't be a doc.
type b128 = tuple;

}
```

produces:
``` md
# World test

# Test Heading

And this is also test data.

## Something else

more test info.
This should not be in docs.
* This also should not be in docs. */
Test World

- Imports:
- type `bstr`
- type `b128`

## Exported types from world `test`

----

### Types

#### `type bstr`
[`bstr`](#bstr)

A Bytes String

#### `tuple b128`

128 bit value - but shouldn't be a doc.

##### Tuple Fields

- `0`: `u64`
- `1`: `u64`

```

I would not expect `//` and `/*` comments to appear in the generated documentation.
And yet, they do.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.