typescript - Finns det något sätt att använda `jsdoc` med `.ts`-filer? Kanske transpilera med babel och sedan använda jsdoc?

Finns det något sätt att använda jsdoc med en TypeScript-fil? Jag försökte använda jsdoc-babel med denna konfiguration

{
  "plugins": [
    "node_modules/jsdoc-babel"
  ],
  "babel": {
    "extensions": [
      "js",
      "es6",
      "jsx",
      "ts",
      "tsx"
    ]
  }
}

Men det fungerar inte, kanske kan vi transpilerar ts-filer manuellt och sedan generera jsdocs? Jag känner till alternativ som typedoc men det saknar många viktiga funktioner.

Så använder ni jsdoc med typescript ändå?

Svar #1

Även om @Remi har sagt att TypeDoc är bättre för TypeScript, använder jag JSDoc för bättre jsdoc till markdown-konvertering (vid tiden för denna skrivning).

Metod 1:

Kompilera TypeScript och använd JSDoc med kompilera kod

> tsc && nodemon node_modules/.bin/jsdoc -c jsdoc.json dist/**/*

Metod 2:

Jag använder nedanstående metod med jsdoc2markdown (som använder jsdoc). Jag använder jsdoc-babel, @babel/cli, @babel/core, @babel/preset-env, @babel/preset-typescript med nedanstående jsdoc-konfiguration:

{
  "source": {
    "includePattern": ".+\\.ts(doc|x)?$",
    "excludePattern": ".+\\.(test|spec).ts"
  },
  "plugins": [
    "plugins/markdown",
    "node_modules/jsdoc-babel"
  ],
  "babel": {
    "extensions": ["ts", "tsx"],
    "ignore": ["**/*.(test|spec).ts"],
    "babelrc": false,
    "presets": [["@babel/preset-env", { "targets": { "node": true } }], "@babel/preset-typescript"],
    "plugins": ["@babel/proposal-class-properties", "@babel/proposal-object-rest-spread"]
  }
}

Denna konfiguration:

  • Utesluter dina filerna your-file.test.ts, your-file.spec.ts och your-file.js från kompilering och dokumentation.
  • Inkluderar your-file.ts, your-file.tsdoc och your-file.tsx
  • Med @babel/preset-env riktas den aktuella Node-versionen för konvertering. (Du kan ändra och testa den enligt dina behov) => Se dokumentationen för preset-env
  • Att använda @babel/preset-typescript ger babel förmågan att analysera TypeScript

Tips och tricks

JSDoc-kommentarer försvinner

Babel och TypeScript tar bort vissa JSDoc-kommentarer under transpilering:

  • babel/babel#6898: transform-flow-strip-types tar bort alla jsdoc-kommentarer
  • babel/babel#5512: Babel mycket konstiga flytta kommentarer

Det finns en hackig lösning för detta genom att lägga till en STUB-kod som ses nedan:

let STUB = 1;

/**
 * Some description
 * @typedef {Object} Config
 * @property {string}  name  - Name of the config.
 * @property {string}  color - Color of choice.
 */
STUB = 1;

export type Config = {
  name: string;
  color: string;
};

Jag skrev en wiki-sida för att använda TypeScript med jsdoc2md med jsdoc-babel för länge sedan.

Det kan hjälpa: https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-document-TypeScript

Metod 3 (TypeDoc)

Detta är inte direkt vad som efterfrågas, men starkt relaterat till det. Följande arbetsflöde kan vara användbart:

  • Använder TypeDoc för att generera HTML-sidor.
  • Att använda typedoc-plugin-markdown för att generera flera MarkDown-sidor.
  • Använder concat-md för att generera en enda MarkDown-sida från flera MarkDown-sidor. (Detta är ett npm-paket som jag nyligen utvecklat för att lösa mitt behov av en enskild MarkDown-sida för JSDoc/TypeScript.)

Exempel

typedoc --plugin typedoc-plugin-markdown --mode file --out docs
npx concat-md --decrease-title-levels --dir-name-as-title docs > README.md

Svar #2

Prova JSDoc-pluginet för TypeScript, som är en del av better-docs-verktygsuppsättningen: https://github.com/SoftwareBrothers/better-docs.

Relaterade artiklar