Сообщение Re[3]: Почему прижились XML-комментарии для документации код от 31.05.2020 13:52
Изменено 31.05.2020 13:54 vsb
Re[3]: Почему прижились XML-комментарии для документации кода
Здравствуйте, 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.
AG>Из-за синтаксического оверхеда xml такие комментарии теряют выразительность.
Предполагается, что ты их читаешь в отрисованном виде. Ты же не читаешь исходный текст сайтов. Idea показывает отрисованную документацию по нажатию кнопки. Другие IDE, думаю, могут так же.
В современных языках обычно используют другие подходы. Rust, Swift, Kotlin используют Markdown. Go вроде вообще от разметки почти отказался. Т.е. да, ты прав, XML оказался не самой лучшей идеей и от него ушли в сторону Markdown. Думаю, в будущем и в старых языках введут альтернативную разметку.
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.
AG>Из-за синтаксического оверхеда xml такие комментарии теряют выразительность.
Предполагается, что ты их читаешь в отрисованном виде. Ты же не читаешь исходный текст сайтов. Idea показывает отрисованную документацию по нажатию кнопки. Другие IDE, думаю, могут так же.
В современных языках обычно используют другие подходы. Rust, Swift, Kotlin используют Markdown. Go вроде вообще от разметки почти отказался. Т.е. да, ты прав, XML оказался не самой лучшей идеей и от него ушли в сторону Markdown. Думаю, в будущем и в старых языках введут альтернативную разметку.
Re[3]: Почему прижились XML-комментарии для документации код
Здравствуйте, 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. Думаю, в будущем и в старых языках введут альтернативную разметку.
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. Думаю, в будущем и в старых языках введут альтернативную разметку.