bug: docs-readme not outputting component docs as expected

[RobM-ADP]

Prerequisites

• [X] I have read the Contributing Guidelines.
• [X] I agree to follow the Code of Conduct.
• [X] I have searched for existing issues that already report this problem, without success.

Stencil Version

2.15.2

Current Behavior

When adding comments to a component, the component level documentation does not get output into the readme at all. It doesn't work on the first generation of the readme file or on subsequent updates

Expected Behavior

The readme should include all the jsdoc comments from the source file

Steps to Reproduce

Create a component with jsdoc comments as seen here:

import { Component, Host, h, Prop, Method } from '@stencil/core';
/**
 * Some comment that should go in the readme
 *
 * @slot - Default slot for content
 */
@Component({
  tag: 'my-hello',
  styleUrl: 'my-hello.css',
  shadow: true,
})
export class MyHello {

  /**
   * A property that is output to the readme correctly
   */
  @Prop() myProp: string;

  /**
   * A method that is output to the readme correctly
   * @returns
   */
  @Method()
  async testMethod() {
    return Promise.resolve('foo');
  }

  render() {
    return (
      <Host>
        <slot></slot>
      </Host>
    );
  }
}

Configure the docs-readme output target in stencil-config

export const config: Config = {
  namespace: 'test-repro',
  outputTargets: [
    {
      type: 'dist',
      esmLoaderPath: '../loader',
    },
    {
      type: 'dist-custom-elements',
    },
    {
      type: 'docs-readme',
    },
    ...

Run the build using npm script:

"scripts": {
    "build": "stencil build --docs",
    ...
}

See the generated readme.md that is missing the component documentation:

# my-hello



<!-- Auto Generated Below -->


## Properties

| Property | Attribute | Description                                       | Type     | Default     |
| -------- | --------- | ------------------------------------------------- | -------- | ----------- |
| `myProp` | `my-prop` | A property that is output to the readme correctly | `string` | `undefined` |


## Methods

### `testMethod() => Promise<string>`

A method that is output to the readme correctly

#### Returns

Type: `Promise<string>`




## Slots

| Slot | Description              |
| ---- | ------------------------ |
|      | Default slot for content |


----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*

Code Reproduction URL

https://github.com/RobM-ADP/stencil-output-target-issue/blob/main/src/components/my-hello/readme.md

Additional Information

No response

[alicewriteswrongs]

Hello @RobM-ADP, and thanks for reporting this issue and for providing a reproduction! I was able to confirm that arbitrary comments in a JSDoc attached to the top of a component class are, as you noted, not making it through to generated README files. Instead, only tags like @slot, as described here, make it through.

I believe at present this is the intended behavior, but I'm going to put this into the backlog so we can look into including comments like this into autogenerated README files. Hopefully if it's not too complicated to add this behavior we'll get a chance to look at it soon.

Thanks for reporting!

[RobM-ADP]

I thought that might be the case and I can kind of understand why that is since you are trying to allow for some of the readme to be hand coded and some to be auto-generated. It would be nice if there was a way to integrate both. Perhaps something like a placeholder comment in the readme similar to your <!-- Auto Generated Below --> comment. Where you could do something like:

# MyComponentName
<!-- Auto Generated Start: docs -->Have the content go here<!-- Auto Generated End: docs -->

## Hand written part
Lorem ipsum...

<!-- Auto Generated Below -->
props, methods, etc. generated below as usual

Of even if there was a way to roll my own custom doc generator using some of your existing stuff from here: https://github.com/ionic-team/stencil/blob/main/src/compiler/docs/readme/output-docs.ts

[rwaskiewicz]

@RobM-ADP 👋

The original issue in the GitHub summary has been fixed in Stencil v2.19.0, which was just released. I'm going to close this issue as a result. If this bug should reappear, feel free to open a new issue. Thanks!