История изменений

Детальная документация не про то. Не про то «что» делает функция, а именно про то «как» она это делает.

Что функция делает, обычно понятно по имени или докстрингу (если он есть, конечно); в крайнем случае по коду. Как она это делает, знать особенно незачем, если мы не ковыряем конкретно эту функцию. Меня обычно больше интересует, зачем она делает то, что делает, смысл ее существования и место в общей картине.

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

Детальная документация не про то. Не про то «что» делает функция, а именно про то «как» она это делает.

Что функция делает, обычно понятно по имени или докстрингу (если он есть, конечно). Как она это делает, знать особенно незачем, если мы не ковыряем конкретно эту функцию. Меня обычно больше интересует, зачем она делает то, что делает, смысл ее существования и место в общей картине.

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