Comments and Doc Comments not working as expected.

[stevenj]

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:

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<u8>;

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

}

produces:

# <a id="test"></a>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

#### <a id="bstr"></a>`type bstr`
[`bstr`](#bstr)
<p>A Bytes String

#### <a id="b128"></a>`tuple b128`

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

##### Tuple Fields

- <a id="b128.0"></a>`0`: `u64`
- <a id="b128.1"></a>`1`: `u64`

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

[alexcrichton]

I believe this is currently due to https://github.com/bytecodealliance/wasm-tools/issues/1362

[stevenj]

Its a bit ugly, but the following workaround seems to hide the comment lines that you don't want in docs, at least for markdown.

// <!--- This should not be in docs. -->