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

vsb>>Я не пойму, о чём речь вообще.

AG>Пример документации JavaDoc в комментариях тут
AG>http://www.docjar.net/html/api/java/util/Collections.java.html

AG>По комментариям вида /** ... */ генерируется документация к методам. Можно документировать конкретные параметры (через "@param имя-параметра"), возвращаемое значение и т.д.

AG>В С++ doxygen использует очень схожий подход.

AG>В C# применяют xml комментарии. См пример тут
AG>https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features

AG>Я недоумеваю, зачем использвать xml для комментариев.

В то время, когда создавались эти языки/инструменты, распространённых альтернатив не было. XML был "горячим", все его любили, развивали, интернет взрывался, там тот же XML (HTML). В общем-то очевидно, почему в старых языках был XML. Markdown придумали в 2004 году, популярным он стал ещё позже. Java придумали в 1995 году, C# в 2000 году, Doxygen в 1997 году.

AG>Из-за синтаксического оверхеда xml такие комментарии теряют выразительность.

Предполагается, что ты их читаешь в отрисованном виде. Ты же не читаешь исходный текст сайтов. Idea показывает отрисованную документацию по нажатию кнопки. Другие IDE, думаю, могут так же.

В современных языках обычно используют другие подходы. Rust, Swift, Kotlin используют Markdown. Go вроде вообще от разметки почти отказался. Т.е. да, ты прав, XML оказался не самой лучшей идеей и от него ушли в сторону Markdown. Думаю, в будущем и в старых языках введут альтернативную разметку.