Как вести документацию для компонентов Angular 2+?

Question

[Максим Иванов]

Суть в том, что компонетов становится много, входящих и исходящих (@Input, @Output) параметров много, как разрабатывают в крупных компаниях документацию к своему коду. Это же наверное справедливо и для React. Ведь компонентов много и разбираться в работе каждого имеет мало смысла скорее всего, а если еще и тесты не писать к компонентам, то уже в ад можно попасть. Что делаете вы?

Answer 1

[Ivan Stroykin]

Давать компонентам правильные названия
Таким образом, чтобы при прочтении названия компонента можно было понять, что данный компонент из себя представляет. К примеру: select, datepicker, graph, file-input, editor

Правильно распределять компоненты по директориям
Если компонент является разделом на сайте, то перед наименованием директории в которой хранится этот компонент пишем, к примеру, +. Составляющие части разделов размещаются внутри директории раздела которому они принадлежат.

Выглядит это так: есть страница, допустим, "часто задаваемые вопросы" - "+faq", на которой есть независимые части, такие как, "вопрос/ответ"- "question-answer" и "задать вопрос" - "ask-question". В итоге иерархия получается такой:
-- +faq
---- ask-question
------ ask-question.component.ts
---- question-answer
------ question-answer.component.ts
-- faq.component.ts

Если компонент используется во многих местах (общий компонент), то такие компоненты помещаются в директорию /shared и группируются по смысловой составляющей, к пример:
-- shared
---- forms
------ editors
-------- summernote
------ input
-------- datepicker
-------- select
---- graphs
------ flot-charts
...

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

Для общего документирования приложения можете воспользоваться Dgeni (инструкция)
Для TypeScript можете воспользоваться typedoc

Answer 2

[ozknemoy]

что бы не тратить кучу время на эти модные документации достаточно перед куском кода понятным родным языком писать комментарии. не надо писать ерунду или какие то очевидности на английском. а то бывает смотришь ацкий гомнокод и видишь такой четкий коммент

/*
    * Phone mask on inputs
    * */
    $rootScope.mask = function() {
        $(document).ready(function() {
            $('input[type="tel"]').mask('[phone]');
        });
    }();

Comments

[Stepanya]

Зачем тут комментарий? Что он объясняет? Если я бы видел только

$rootScope.mask

и комментарий

/*
* Phone mask on inputs
* */

я бы предполагал, что это '[phone]' а не функция добавляющая слушателя и назаначающая всем инпутам с типом tel какую-то маску.
Эта функция должна была бы называтся setMaskToAllPhoneInputsByReadyDocument.

[Stepanya]

Кстати, Вы знаете, что ваша функция не работает?

[ozknemoy]

я написал же написал это чужой код. и он работает как iif

[Максим Иванов]

ответ выше более техничен