Здравствуйте, 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 имя-параметра" выглядит как излишество, непонятно, почему не хватило @имя-параметра, или просто имя-параметра.