storybook [Bug]: angular组件的autodoc不包含jsdoc文档

zvokhttg 于 3个月前发布在 Angular

关注(0)|答案(3)|浏览(43)

描述问题

关于同一个问题( #21387 , #11674 )已经关闭，但问题仍然存在。
autodoc文档中不包含来自jsdoc-comments的信息。只需将storybook添加到现有的angular项目中，检查Example/Button(在安装storybook期间创建)的文档，如下所示：

我已在stackblitz上创建了一个复现(上传了我的本地项目),但在创建此问题时，在stackblitz上运行npm install总是失败，出现ECONNRESET错误。从stackblitz下载项目并尝试本地运行可以解决问题。

复现链接

https://stackblitz.com/edit/stackblitz-starters-dcmzh2

复现步骤

ng new storybook-doc-test --create-application=false
cd storybook-doc-test
ng g library @sb/doc-test
npx storybook@latest init (关于compodoc的问题回答是肯定的，但问题仍然存在，如果回答是否定的)
由于最新的compodoc版本依赖于angular 18(这会导致在npm install过程中出现警告，因为我正在使用的node版本与angular 18不兼容),我已经将compodoc的版本更改为“1.1.21”
npm install 再次
npm run storybook
=> 查看由storybook本身创建的button-component的文档 => 所有jsdoc注解都不会出现在文档中，因此它非常无用。

系统

Storybook Environment Info:

  System:
    OS: Windows 10 10.0.19045
    CPU: (16) x64 AMD Ryzen 7 PRO 4750U with Radeon Graphics   
  Binaries:
    Node: 18.19.0 - C:\Program Files\nodejs\node.EXE
    Yarn: 1.22.21 - ~\AppData\Roaming\npm\yarn.CMD
    npm: 10.2.3 - C:\Program Files\nodejs\npm.CMD <----- active
    pnpm: 8.4.0 - ~\AppData\Roaming\npm\pnpm.CMD
  Browsers:
    Chrome: 114.0.5735.134
    Edge: Chromium (126.0.2592.87)
  npmPackages:
    @storybook/addon-docs: ^8.2.0 => 8.2.0
    @storybook/addon-essentials: ^8.2.0 => 8.2.0
    @storybook/addon-interactions: ^8.2.0 => 8.2.0
    @storybook/addon-links: ^8.2.0 => 8.2.0
    @storybook/addon-onboarding: ^8.2.0 => 8.2.0
    @storybook/angular: ^8.2.0 => 8.2.0
    @storybook/blocks: ^8.2.0 => 8.2.0
    @storybook/test: ^8.2.0 => 8.2.0
    storybook: ^8.2.0 => 8.2.0

其他上下文

用于创建项目的angular CLI版本为17.3.8。

storybook

来源：https://github.com/storybookjs/storybook/issues/28506

3条答案

按热度按时间

mec1mxoz1#

要解决Angular组件的autodoc文档中JSDoc注解不显示的问题，请按照以下步骤操作：

确保Compodoc已正确集成，通过验证/code/addons/docs/angular/index.js中的setCompodocJson函数：

import { global } from '@storybook/global';

export const setCompodocJson = (compodocJson) => {
  global.__STORYBOOK_COMPODOC_JSON__ = compodocJson;
};

检查Compodoc JSON是否正确生成并传递给Storybook。可以通过手动运行Compodoc并确保JSON输出包含JSDoc注解来实现这一点。
验证您在Angular项目中的tsconfig.json是否包含处理JSDoc注解所需的设置。tsconfig.json应与/code/frameworks/angular/src/client/docs/__testfixtures__/doc-button/tsconfig.json中的一个相似：

{
  "extends": "../../../tsconfig.json",
  "compilerOptions": {
    "rootDir": "."
  },
  "include": ["./*.ts"]
}

确保doc-button.component.ts文件包含JSDoc注解，并且这些注解格式正确。示例：

/**
* Button component
* @example
* <app-doc-button></app-doc-button>
*/
@Component({
  selector: 'app-doc-button',
  templateUrl: './doc-button.component.html',
  styleUrls: ['./doc-button.component.scss']
})
export class DocButtonComponent {
  /**
* Button label
*/
  @Input() label: string;
}