Пример хорошей доки №1 - PyTorch

Чтобы не делать cherry-pick - берем рандомную страничку в доке

И тут нас встречает такая красивая вставочка на латехе. Первое что можно отметить - дока сгенерена пофайлово в конкретно этом разделе, что очень близко к нам. Описание алгоритма для такого кейса довольно крутая штука, которая освобождает от объяснения аспектов имплементации.

Идем дальше:

Описание параметров интересно тем, что здесь идёт пояснение что и зачем использовать, а не просто рассказ что там за что отвечает. Ну и прикольный note.

Остальная информация здесь организована +- похожим образом, хотя и стоит отметить что те же методы довольно типисчные для обычной доки по методам без таких пояснений.

Выводы?

ИМХО, в пофайловой доке имеет смысл обильно комментировать только "мясо" - основная сигнатура, на которую опирается файл или модуль, остальные штуки гораздо менее значительны, и комментировать их прям с примерами и какими-то йоба-пояснениями не сильно поможет. Да, возможно что-то окажется за бортом и кто-то пострадает - но зато сами пофайловые доки могут быть более доступны и менее тягомотны.

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