Почему смирились с этим ужасом, тогда как можно ведь JavaDoc (Doxygen, etc) или даже нормальные комментарии?

Навеяно веткой про TeX

Потому что XML это стандарт,
а JavaDoc гнусная оракловая пропиертарщина.

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

AG>Почему смирились с этим ужасом, тогда как можно ведь JavaDoc (Doxygen, etc) или даже нормальные комментарии?

Потому, что это единственный вид комментариев поддерживаемый компилятором. И так как он поддерживается без дополнительных утилит из коробки, то он и используется. Места для голосования и предпочтений тут нет.

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

AG>Почему смирились с этим ужасом, тогда как можно ведь JavaDoc (Doxygen, etc) или даже нормальные комментарии?

Посмотри, как это в Go сделано. Пишешь нормальные коментарии, без какой-либо особой разметки, а специально обученная утилита превращает их в красивую документацию.

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

Pzz>Посмотри, как это в Go сделано. Пишешь нормальные коментарии, без какой-либо особой разметки, а специально обученная утилита превращает их в красивую документацию.

Ну вот в Go хорошо сделано.

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

Я не понимаю, зачем уже после изобретения JavaDoc было делать этот шаг назад с использованием xml.

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

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

AG>В духе doxygen / JavaDoc тоже приемлемо — получается читабельный комментарий, без большого количества лишнего мусора.

AG>Я не понимаю, зачем уже после изобретения JavaDoc было делать этот шаг назад с использованием xml.

Я думаю маркетологи виноваты. В то время XML пихали где надо и где не надо.

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

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

AG>>Почему смирились с этим ужасом, тогда как можно ведь JavaDoc (Doxygen, etc) или даже нормальные комментарии?

Pzz>Посмотри, как это в Go сделано. Пишешь нормальные коментарии, без какой-либо особой разметки, а специально обученная утилита превращает их в красивую документацию.

А чем это отличается от JavaDoc? Кроме того, что в Го надо // использовать, а в JavaDoc /** .. */? Все остальные конструкции в JavaDoc не являются обязательными. Не хочешь — не используй, будет как в Го. А хочешь — используй, будет лучше. В JavaDoc в доки можно вставить кусок программы как пример использования.

Для сравнения в Го

В документации пример есть
https://golang.org/pkg/strings/#ToUpper

а в коде — нет. Т.е. его с какими-то приседаниями туда вставляли
https://golang.org/src/strings/strings.go?s=13714:13743#L544

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

B>А чем это отличается от JavaDoc? Кроме того, что в Го надо // использовать, а в JavaDoc /** .. */? Все остальные конструкции в JavaDoc не являются обязательными. Не хочешь — не используй, будет как в Го. А хочешь — используй, будет лучше. В JavaDoc в доки можно вставить кусок программы как пример использования.

В Go документация делается из обычных комментариев. Ему все равно, // ты напишешь, или /* ... */

B>а в коде — нет. Т.е. его с какими-то приседаниями туда вставляли
B>https://golang.org/src/strings/strings.go?s=13714:13743#L544

Примеры берутся из файла example_test.go, где они написаны просто как код на Go. И сами, автоматически, попадают на нужное место. В процессе их еще и проверят, что они компилируются.

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

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

B>>А чем это отличается от JavaDoc? Кроме того, что в Го надо // использовать, а в JavaDoc /** .. */? Все остальные конструкции в JavaDoc не являются обязательными. Не хочешь — не используй, будет как в Го. А хочешь — используй, будет лучше. В JavaDoc в доки можно вставить кусок программы как пример использования.

Pzz>В Go документация делается из обычных комментариев. Ему все равно, // ты напишешь, или /* ... */

Я к тому, что в Явадоке тебя ХМЛ не заставляют использовать. Можно писать документацию и в стиле Го. А вот в Го писать в стиле Явадока не выйдет.

B>>а в коде — нет. Т.е. его с какими-то приседаниями туда вставляли
B>>https://golang.org/src/strings/strings.go?s=13714:13743#L544

Pzz>Примеры берутся из файла example_test.go, где они написаны просто как код на Go. И сами, автоматически, попадают на нужное место. В процессе их еще и проверят, что они компилируются.

В Яве я могу перейти к сорцам, посмотреть код, потом доки и примеры, всё в одном месте. А тут придётся между файлами прыгать.

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

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

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

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

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

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

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

Даже "@param имя-параметра" выглядит как излишество, непонятно, почему не хватило @имя-параметра, или просто имя-параметра.

Здравствуйте, 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. Думаю, в будущем и в старых языках введут альтернативную разметку.

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

B>Я к тому, что в Явадоке тебя ХМЛ не заставляют использовать. Можно писать документацию и в стиле Го. А вот в Го писать в стиле Явадока не выйдет.

На самом деле не можешь. Без <p> javadoc всё в одну строчку схлопнет, например. Ну разве что ты javadoc в принципе не используешь, а читаешь документацию исключительно в IDE путём перехода к реализации.

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

AG>Почему смирились с этим ужасом, тогда как можно ведь JavaDoc (Doxygen, etc) или даже нормальные комментарии?

Все просто: 1) близость к HTML 2) неограниченные возможности 3) стандарт

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

AG>Почему смирились с этим ужасом, тогда как можно ведь JavaDoc (Doxygen, etc) или даже нормальные комментарии?

Уже лет 10 точно (дольше, но не вспомню с какого момента) пишу комментарии Doxygen. XML в каком-то микрософте, как ты сказал, но микрософт же никогда не умел программное обеспечение разрабатывать Хотя местами делает это довольно успешно, чего уж.

Смешной случай с XML–комментариями. Совсем недавно в Apple залатали много лет существующую эпичнейшую бажилищу, ломающую XML–парсер невалидными комментариями определенного вида. Причем, в критичном с точки зрения безопасности месте: с помощью XML–коммента можно было, до iOS 13.5, обходить sandbox из любой непривилегированной приложеньки

Дыра, ИМХО, настолько хрестоматийная, что заслуживает памятника и внесения в анналы истории для обучения потомков:

https://siguza.github.io/psychicpaper/