Инструменты и руководство для документирования кода TypeScript?

Существуют ли какие-либо инструменты для создания документации для TypeScript исходного кода? Или я должен использовать что-то общее, например NaturalDocs? Каким будет рекомендуемый стиль комментариев блоков/предназначенных для автономного объема документации.

Должен ли я использовать:

///<foo>bar</foo> MSVS kind of comments?

или

/** @javadoc style comments */

или, возможно,

/*
  Something like this?
 */

Я боюсь использовать ///, потому что он используется для импорта, и я не хочу наступать на некоторые другие будущие функции, которые могут быть введены аналогичным образом, но вы никогда не знаете...

Или можно создать документированный JavaScript из TypeScript, а затем использовать инструментальную цепочку JavaScript?

Ответ 1

Возможно, немного поздно, но после того, как я столкнулся с этой проблемой, я обнаружил, что инструментов для этого еще не было. Поэтому я форсировал компилятор TS и создал код для этого.

Запустил проект компилятора TypeScript в версии v.0.9.0.1, затем добавил параметр "-документация", который будет генерировать wiki-документацию из любого JSDoc, который вы ввели в код (ни один не требуется для простого вывода методов/свойств и т.д. )

https://typescript.codeplex.com/SourceControl/network/forks/EdwardNutting/TypeScriptDocumentationGeneration

Он создает файлы .ts.wiki(содержимое которых подходит для загрузки прямо в CodePlex и т.д., если вы также используете новые параметры --wikiRemoveRoot и --wikiSourceRoot - см. fork - мое первое описание фиксации). Или вы могли бы адаптировать код для создания HTML (что было бы относительно просто - я проделал тяжелую работу по искажению компилятора /delcrationEmitter:))

Надеюсь, что это поможет (вам или будущим читателям этого вопроса)

Ответ 2

Я только что выпустил инструмент под названием TypeDoc, который генерирует страницы документации html api из файлов TypeScript *.ts.

Генератор документации запускает компилятор TypeScript и извлекает информацию о типе из генерируемых символов компилятора. Поэтому вам не нужно включать какие-либо дополнительные метаданные в ваши комментарии.

Если вы хотите попробовать, просто установите и запустите инструмент через npm:

npm install typedoc --global
typedoc --out path/to/documentation/ path/to/typescript/project/

Если вы хотите узнать, как выглядит документация, созданная с помощью TypeDoc, перейдите на страницу GitHub проекта:

http://typedoc.org/ | https://github.com/TypeStrong/typedoc

Ответ 3

Вы можете использовать такой комментарий над своей функцией.

/** 
* Comment goes here
*/

И затем, когда вы ударите свой метод, он появится с документацией.

Ответ 4

Сгенерировать комментарии XML Doc - одна из предлагаемых проблем для языка TypeScript.

На данный момент TypeScript инструменты поддерживают JSDoc Объявление TypeScript 0.8.2.

Итак, вы определенно хотите использовать стиль JSDoc для комментариев. Если вам нужны комментарии только для IntelliSense - использование JSDoc будет отвечать вашим требованиям. Если вам нужны комментарии, потому что вы хотите предоставить документацию для своих пользователей API, вы должны использовать файлы декларации (*.d.ts) с комментариями. Если вы хотите создать хорошую документацию на веб-сайте, я думаю, будет легко подождать, когда команда TypeScript будет генерировать комментарии XML-документов (или написать их вручную).

Ответ 5

Я компилирую JavaScript и использую jsduck (https://github.com/senchalabs/jsduck) для создания документации api на основе файлов JavaScript. Пока вы не укажете tsc, чтобы удалить комментарии, которые отлично работают, кроме полей без значения по умолчанию (!).

module example {

/**
 * My class description
 * @class example.MyClass
 */
export class MyClass {
    /**
     * Description of my property
     * @property {String} myProperty
     */
    myProperty: string = null;

    /**
     * This property will be removed in compiled JavaScript, that why
     * this documentation will not be visible in jsduck.
     */
    willNotWork: string;

    /**
     * Description of my method
     * @method myFunction
     * @param {String} myParam
     */
    myFunction(myParam: string): void {
    }
}

} // end of module

Ответ 6

Я написал инструмент для создания документации HTML из файлов декларации (.d.ts) здесь. Он имеет базовую поддержку комментариев в стиле JSDoc.

Скомпилируйте исходные файлы TypeScript с параметрами -d -c для создания файлов декларации и сохранения комментариев. Затем после установки вы можете запустить

typescript-docs *.d.ts

для создания документации HTML на стандартном выходе.

Чтобы сохранить вывод в файл, используйте

typescript-docs *.d.ts --output=path/to/output.html