Вот делают всякие-там XML-комментарии.

По-моему это тупо. Вместо этого нужно было сделать:
1) специализированный встроенный редактор, например HTML с просмотром;
2) навигацию от любого элемента кода к странице, открываемой на редактирование в редакторе документации.

Т исходный код бы не замусоривался

И возможностей по редактированию было бы больше: картинки, например, с диаграммами видеть в wysiwyg.

Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>Вот делают всякие-там XML-комментарии.

AS>По-моему это тупо. Вместо этого нужно было сделать:
AS>1) специализированный встроенный редактор, например HTML с просмотром;
AS>2) навигацию от любого элемента кода к странице, открываемой на редактирование в редакторе документации.
AS>Т исходный код бы не замусоривался
AS>И возможностей по редактированию было бы больше: картинки, например, с диаграммами видеть в wysiwyg.

А вы хорошо смотрели? https://www.ultimatepp.org/app$ide$Topic$en-us.html

Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>И возможностей по редактированию было бы больше: картинки, например, с диаграммами видеть в wysiwyg.
Потому, что у такого варианта недостатков больше, чем достоинств.
Плюсов никаких (можно и так в любой вики написать что угодно и поставить туда ссылку из кода).
А минусов много. Как минимум два:
— привязка к конкретной IDE
— разсинхронизация документации с кодом, так как компилятор уже не имеет возможности проверить документацию

Здравствуйте, vmpire, Вы писали:

V>Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>>И возможностей по редактированию было бы больше: картинки, например, с диаграммами видеть в wysiwyg.
V>Потому, что у такого варианта недостатков больше, чем достоинств.
V>Плюсов никаких (можно и так в любой вики написать что угодно и поставить туда ссылку из кода).
V>А минусов много. Как минимум два:
V>- привязка к конкретной IDE
Фигня, всегда можно экспортировать в pdf или кучу html и упаковать в chm или распечатать нужное

V>- разсинхронизация документации с кодом, так как компилятор уже не имеет возможности проверить документацию
Дык поддерживать синхронизацию с кодом всё равно придётся при документировании. И потом часть документации должна описывать вовсе не код.
А то что doxygen генерит как правило лютое гуано не пригодное как документация, так как коментарии по куду чисто формальные

Здравствуйте, Arsen.Shnurkov, Вы писали:

Стандартов на формат документации нет

Здравствуйте, vmpire, Вы писали:

V>А минусов много. Как минимум два:
V>- привязка к конкретной IDE

Давно бы уже пора выработать стандарт на функции IDE (можно по уровням — базовый типа "подсветка синтаксиса", посложнее и совсем сложный), и универсальные стандартные форматы файлов проектов, файлов документации и прочего, не относящегося напрямую к языку программирования. Или по крайней мере внутри языка программирования, чтобы проекты на С++ можно было открывать в любой среде разработки.

V>- разсинхронизация документации с кодом, так как компилятор уже не имеет возможности проверить документацию

Давно бы уже пора чтобы компилятор проверял, согласована ли документация с кодом. Все что для этого нужно — хранить контрольные суммы и времена последней модификации каждого блока кода (при компиляции достаточно делать сериализацию синтаксического дерева в файл) и аналогично для документации (если это xml — то компилятору проверить по специальным тегам будет несложно). И специальный режим компиляции с проверкой соответствия кода и доков.

Здравствуйте, kov_serg, Вы писали:

V>>А минусов много. Как минимум два:
V>>- привязка к конкретной IDE
_>Фигня, всегда можно экспортировать в pdf или кучу html и упаковать в chm или распечатать нужное
А редактировать-то как в pdf? Привязка к IDE именно для редактирования.

V>>- разсинхронизация документации с кодом, так как компилятор уже не имеет возможности проверить документацию
_>Дык поддерживать синхронизацию с кодом всё равно придётся при документировании.
Компилятор часть проверок берёт на себя независимо от IDE.
_> И потом часть документации должна описывать вовсе не код.
Эту часть обычно пишут вообще отдельно от кода, тут специальная IDE не нужна вообще

_>А то что doxygen генерит как правило лютое гуано не пригодное как документация, так как коментарии по куду чисто формальные
Ну это не проблема инструмента. Если разработчики пишут отписки вместо нормального документирования, то никакая специальная IDE этого не изменит.

Здравствуйте, anonymouse2, Вы писали:

A>Давно бы уже пора выработать стандарт на функции IDE (можно по уровням — базовый типа "подсветка синтаксиса", посложнее и совсем сложный), и универсальные стандартные форматы файлов проектов, файлов документации и прочего, не относящегося напрямую к языку программирования. Или по крайней мере внутри языка программирования, чтобы проекты на С++ можно было открывать в любой среде разработки.
Ага. И давно пора придумать один язык, чтобы на нём общаться
Если придумают такой стандарт — просто будет на один стандарт больше. Потому, что 99% людей он будет не нужен. Нет потребности.
Если есть желание — придумайте.

V>>- разсинхронизация документации с кодом, так как компилятор уже не имеет возможности проверить документацию
A>Давно бы уже пора чтобы компилятор проверял, согласована ли документация с кодом.
Он и сейчас проверяет. Сама документация ведь в коде.

A>Все что для этого нужно — хранить контрольные суммы и времена последней модификации каждого блока кода (при компиляции достаточно делать сериализацию синтаксического дерева в файл) и аналогично для документации (если это xml — то компилятору проверить по специальным тегам будет несложно). И специальный режим компиляции с проверкой соответствия кода и доков.
Есть специальный режим компиляции для _создания_ доков.

Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>1) специализированный встроенный редактор, например HTML с просмотром;
AS>2) навигацию от любого элемента кода к странице, открываемой на редактирование в редакторе документации.

AS>Т исходный код бы не замусоривался

Это привязывает только к одной IDE. Нельзя будет посмотреть комментарии в другом текстовом редакторе.


AS>И возможностей по редактированию было бы больше: картинки, например, с диаграммами видеть в wysiwyg.

Всё в твоих руках — возьми какую-нибудь IDE с открытыми исходниками и doxygen или другое средство подготовки документации. Интегрируй их и добавь эти возможности. Если эта реализация многим понравится, постепенно такие возможности появятся во всех IDE.

Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>По-моему это тупо. Вместо этого нужно было сделать:
AS>1) специализированный встроенный редактор, например HTML с просмотром;
AS>2) навигацию от любого элемента кода к странице, открываемой на редактирование в редакторе документации.

Это недостаточно радикально.
Нужно встроить проверку документации в компилятор.
Не написал комментарий — программа не собирается.

Эти уроды (программисты) не пишут даже для чего предназначен файл и класс.
Поубивал бы.

Здравствуйте, alpha21264, Вы писали:

A>Нужно встроить проверку документации в компилятор.
A>Не написал комментарий — программа не собирается.

Достаточно встроить проверку в процедуру code review.
Не написал комментарий — ревьюверы не разрешили влить изменения.

А так, дурное дело нехитрое, родить правила для линта.

A>Эти уроды (программисты) не пишут даже для чего предназначен файл и класс.
A>Поубивал бы.

Против линта есть простой приём:

// This class is useful.
class M {
  . . . .
  void foo(); // This method is useful.
  void bar(); // This method is useful.
};

И линт доволен, и программист отбоярился, и коллеги в ярости.

Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>Вот делают всякие-там XML-комментарии.

А надо делать просто комментарии, с минимальным форматированием.
В духе javadoc'ов-doxygen'ов, или вообще без маркапа.
Которые IDE выглядят не как мусор, а как документация-по-месту.

Здравствуйте, Alexander G, Вы писали:

AG>А надо делать просто комментарии, с минимальным форматированием.
AG>В духе javadoc'ов-doxygen'ов, или вообще без маркапа.
AG>Которые IDE выглядят не как мусор, а как документация-по-месту.

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

AS>2) навигацию от любого элемента кода к странице, открываемой на редактирование в редакторе документации.
Что такое элемент кода, и что делать с документацией на "элемент", если его делят на части, которые перетасовываются по разным местам?

Здравствуйте, Arsen.Shnurkov, Вы писали:

По C#. Я время от времени раздумываю над подходом — документация как компилируемый проект. Т.е. заводится отдельный проект, в котором есть ссылки на документируемые сборки. С помощью навигации по типам (jquery подоход) выбираются узлы — сборки, типы, методы, поля и к ним добавляется мета информация (описания и связи), по которой потом можно потом сгенерить текст или диаграммы.

Вроде бы плюсов много — код чистый, при рефакторинге названия автоматически переименовываются, несложно добавить инструмент, который по узлу (сборка, тип, метод, поле) смог бы найти текст и показать удобным для разработчика способом.

Здравствуйте, alpha21264, Вы писали:

A>Это недостаточно радикально.
A>Нужно встроить проверку документации в компилятор.
A>Не написал комментарий — программа не собирается.

Следующим шагом будет проверка соответствия смысла кода и комментария. А поскольку локально делать это пока никто не осилил, то компилятор будет постоянно лазить в нейронную сеть какого-нибудь гугля. Таким образом, все программирование в мире довольно быстро окажется у гугля под колпаком.

Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>Вот делают всякие-там XML-комментарии.

AS>По-моему это тупо. Вместо этого нужно было сделать:

Имхо главная проблема "inline" документации — очень быстрое деградирование. Причем автоматические средства рефакторинга имхо качественно эту проблему усилили.

Здравствуйте, Кодт, Вы писали:

К>И линт доволен, и программист отбоярился, и коллеги в ярости.

Тут можно в кошки-мышки поиграть.
Добавить правило линтеру не пропускать комментарии такого плана

Здравствуйте, Кодт, Вы писали:
К>Достаточно встроить проверку в процедуру code review.
К>Не написал комментарий — ревьюверы не разрешили влить изменения.
Ещё лучше — привязывать всю переписку в code review в виде комментариев в код.
Получится автобаланс: очевидные места никто документировать не будет; писать отмазки в стиле джавадока (int getNextPrimeNumberUsingRiemannHypothesis(int i) // accepts int; returns int) тоже не будет.
Зато будут откомментированы все неожиданности типа "we did already try all the verbs on the previous run, so it's safe to exit now".

Здравствуйте, Arsen.Shnurkov, Вы писали:

AS>Вот делают всякие-там XML-комментарии.

AS>По-моему это тупо. Вместо этого нужно было сделать:

Посмотри, как это сделано в Golang. Я раньше думал, что вся эта автоматически сгенерированная документация — это чушь полная, и документацию надо отдельно писать руками. Сейчас так не думаю.

Hint: вся документация по этой ссылке — автоматически сгенерированная.

Здравствуйте, Pzz, Вы писали:

Pzz>Посмотри, как это сделано в Golang. Я раньше думал, что вся эта автоматически сгенерированная документация — это чушь полная, и документацию надо отдельно писать руками. Сейчас так не думаю.

Одно не заменяет другое. Автоматически сгенерированная дока — это что-то типа справочника, т.е. лишь часть документации.
Есть же еще вводные статьи, описание концепций, основных сценариев, примеры и т.д.


Pzz>Hint: вся документация по этой ссылке — автоматически сгенерированная.

Это вся документация?
Ни о чём совершенно, двойка сходу.

Сравнить с этой докой:
http://www.boost.org/doc/libs/1_65_1/doc/html/program_options/tutorial.html