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

Question

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

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

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

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

или

/** @javadoc style comments */

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

/*

  Something like this?

 */

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

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

729 6

typescript documentation-generation

6 ответов:

Comments

Ничего не найдено.

Ed Nutting · Accepted Answer · 2013-08-16 01:18:34

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

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

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

Она производит .ТС.Вики файлы (содержание которых предназначен для загрузки прямо на сайте CodePlex и т. д. если вы также используете новые параметры -- wikiRemoveRoot и --wikiSourceRoot-см. fork-my first commit description). Или вы можете адаптировать код для создания HTML (что было бы относительно просто - я проделал тяжелую работу по искажению компилятор/delcrationEmitter :) )

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

Эд

sebastian-lenz · Accepted Answer · 2016-11-16 17:45:34

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

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

Если вы хотите попробовать его, просто установите и запустите утилиту через npm:
npm install typedoc --global
typedoc --out path/to/documentation/ path/to/typescript/project/
Если вы хотите знать, что a документация, созданная с помощью TypeDoc, выглядит так: перейдите на страницу GitHub проекта:

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

Daniil T. · Accepted Answer · 2014-09-09 20:52:48

вы можете использовать этот вид комментирования вышеуказанной функции.
/** 
* Comment goes here
*/
и затем, когда вы нажмете свой метод, он появится с документацией.

outcoldman · Accepted Answer · 2013-04-28 19:57:22

генерировать комментарии XML Doc один из предложенных вопросов для языка машинописи.

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

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

Christoph Lütjen · Accepted Answer · 2014-06-27 18:51:31

я компилирую в 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's 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

Phil Freeman · Accepted Answer · 2016-08-16 18:16:36

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

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

typescript-docs *.d.ts

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

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

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