Всем привет, как лучше всего писать документацию к открытому API? стоит ли использовать комментарии для документирования? или может лучше вручную через какойнить sphinx doc написать?
Сам я стараюсь писать максимально понятный код, и чтобы при прочтение его было сразу понятно что конкретно он делает, но все же иногда нужны уточнения либо более подробное описание, впринципе не было с этим проблем - я просто добавлял комментарий к какому-то сложному методу. Но все же документаци нужна, понятное дело, что к примеру, туториал удобнее отдельно писать используя тот же sphinx doc, но вот API reference удобнее вообще писать и поддерживать через комментарии, но тогда он начинает захламлять код и больше всего бесит, что иногда приходится писать что-то вроде этого:
/++ Background colors +/
enum Background {
transparent, /// Transparent
light, /// Light background
dark, /// Dark background
action /// Background for actions
}
Еще вопрос - стоит ли писать коментарии к override методам?
Ну и конечно же комментарии удобны тем, что можно быстро получить хелп по данному методу.
Но если же лучше писать внешную документацию вручную, то как лушче всего ее поддерживать в актуальном состоянии?
