Markdown — один из самых популярных языков разметки в мире. Созданный Джоном Грубером в 2004 году, Markdown — это простой и легкий язык разметки, который позволяет добавлять элементы форматирования в обычный текст.
Markdown не зависит от платформы и может быть использован практически в любом приложении. В результате он получил широкое применение в веб-разработках, таких как блоги, документы, блокноты, электронная почта и т.д.
Как работает Markdown?
Как уже упоминалось, Markdown — это язык разметки. Поэтому вы работаете в файле, заканчивающемся расширением .md или .markdown. Этот файл содержит элементы форматирования, такие как заголовки, блоки кода, отступы, выравнивания и т. д.
Документ в формате markdown обрабатывается приложением, известным как Markdown processor или parser. Затем парсер принимает отформатированный текст и создает документ HTML. Затем HTML-документ можно просмотреть в браузере или любом другом приложении, которое его поддерживает.
Что такое комментарий в формате Markdown?
Комментарий Markdown — это текст, добавленный в файл Markdown, но игнорируемый приложением рендеринга. Таким образом, комментарий в формате Markdown не отображается в сгенерированном выводе.
«ЗАЧЕМ ТЫ ЭТО СДЕЛАЛ?» — 9 — авторская программа архитектора Марии Романовой (Maria Romanova/MARO)
Комментарии полезны, когда вам нужно включить в документ скрытый текст, который виден только автору документа, но не отображается в итоговом документе.
Как вставлять комментарии в формате Markdown
К сожалению, Markdown не обеспечивает встроенную поддержку комментариев. Однако вы можете использовать импортированные решения для добавления комментариев в документ Markdown.
Способ 1
Первый синтаксис для добавления комментария в Markdown — это размещение текста комментария внутри пары квадратных скобок, за которыми следуют двоеточие, пробел и знак фунта.
Синтаксис выглядит следующим образом:
[текст_комментария]: #
Текст внутри квадратных скобок рассматривается как комментарий и игнорируется рендерером Markdown.
Пример показан на рисунке:
## Иллюстрация комментария в формате Markdown Это абзац [это комментарий]: # Комментарий выше не виден.
В приведенном выше примере мы имеем простой синтаксис Markdown с заголовком, абзацем, комментарием и еще одним абзацем.
Метод 2
Синтаксис, приведенный ниже, также может вставлять комментарии в документ Markdown.
[//]: # (текст комментария помещается сюда)
Это считается наиболее совместимым с платформами форматом для добавления комментариев.
Другая вариация этого синтаксиса выглядит следующим образом:
[//]: # «текст комментария помещается здесь».
Метод 3
В некоторых движках Markdown можно пропустить две прямые косые черты и использовать следующий синтаксис:
[]: # (текст комментария)
[]: # «текст комментария»
Источник: g-soft.info
Дмитрий Муратов и Алексей Венедиктов* / Персонально ваш // 08.07.23
Генератор документации
Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и, в некоторых случаях, по исполняемым модулям (полученным на выходе компилятора).
Обычно, генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы (типам, классам и их членам/свойствам/методам, процедурам/функциям и т. п. ). В ходе анализа также используется мета-информация об объектах программы, представленная в виде документирующих комментариев. На основе всей собранной информации формируется готовая документация, как правило, в одном из общепринятых форматов — HTML, HTMLHelp, PDF, RTF и других.
Документирующие комментарии
Документирующий комментарий — это особым образом оформленный комментарий к объекту программы, предназначенный для использования каким-либо конкретным генератором документации. От того, какой генератор документации применяется, зависит синтаксис конструкций, используемых в документирующих комментариях.
В документирующих комментариях может содержаться информация об авторе кода, описываться назначение объекта программы, смысл входных и выходных параметров — для функции/процедуры, примеры использования, возможные исключительные ситуации, особенности реализации.
Пример документирующего комментария к функции в программе на Java, предназначенного для использования Javadoc:
Популярные генераторы документации
Наиболее известные генераторы документации:
- perldoc[1] — для Perl. Включен в стандартный дистрибутив.
- Javadoc — для программ на Java
- Doxygen
- NDoc[2] и Sandcastle — для программ на C#, VB.NET и других языков платформы .NET
- Doc-O-Matic[3]
- Document! X
- Epydoc для Питона
- HappyDoc[4]
- PHPDoc — адаптация Javadoc для использования с PHP
- phpDocumentor — PHP ориентированный генератор документации
- POD
- RDoc для Ruby[5]
- ROBODoc[6]
- TwinText
- VBdocman [7] для VB6
- VSdocman (ранее VBdocman .NET) для VB.NET и C#
- WEB / CWEB[8]
- XHelpGen — для проектов на Delphi, входит в состав библиотеки KOL/MCK
- PasDoc[9] — для Delphi/Pascalcs:Generátor dokumentace
Источник: www.sbup.com
Комментарии
Комментарии являются немаловажной частью любого языка программирования, т.к. позволяют удобно пояснять различные участки кода. В C# используются традиционные комментарии в стиле С — однострочные (//. ) и многострочные (/* . . . */):
// Это однострочный комментарий /* Это уже многострочный комментарий */
Все, что находится в однострочном комментарии — от // до конца строки — игнорируется компилятором, как и весь многострочный комментарий, расположенный между /* и */. Очевидно, что в многострочном комментарии не может присутствовать комбинация */, поскольку она будет трактоваться как конец комментария.
Многострочный комментарий можно помещать в одну строку кода:
Console.WriteLine (/* Здесь идет комментарий! */ «Это скомпилируется»);
Встроенные комментарии вроде этого нужно применять осторожно, потому что они могут ухудшить читабельность кода. Однако они удобны при отладке, скажем, когда необходимо временно попробовать запустить программу с указанным другим значением:
DoSomethingMethod (Width, /*Height*/ 100);
Символы комментария, включенные в строковый литерал, конечно же, трактуются как обычные символы:
string s = «/* Это просто нормальная строка */»;
Документация XML
В дополнение к комментариям в стиле C, проиллюстрированным выше, в C# имеется очень искусное средство, на которое я хочу обратить особое внимание: способность генерировать документацию в формате XML на основе специальных комментариев. Это однострочные комментарии, начинающиеся с трех слешей (///) вместо двух. В таких комментариях можно размещать XML-дескрипторы, содержащие документацию по типам и членам типов, используемым в коде.
XML-дескрипторы, распознаваемые компилятором, перечислены в следующей таблице:
| Помечает текст в строке как код | |
| Помечает множество строк как код | |
| Помечает пример кода | |
| Документирует класс исключения (синтаксис проверяется компилятором) | |
| Включает комментарии из другого файла документации (синтаксис проверяется компилятором) | |
| Вставляет список в документацию | |
| Помечает параметр метода (синтаксис проверяется компилятором) | |
| Указывает, что слово является параметром метода (синтаксис проверяется компилятором) | |
| Документирует доступ к члену (синтаксис проверяется компилятором) | |
| Добавляет описание члена | |
| Документирует возвращаемое методом значение | |
| Представляет перекрестную ссылку на другой параметр (синтаксис проверяется компилятором) | |
| Представляет раздел «see also» («смотреть также») в описании (синтаксис проверяется компилятором) | |
| Представляет краткий итог о типе или члене | |
| Описывает свойство |
Чтобы увидеть, как это работает, рассмотрим пример кода, в который добавим некоторые XML-комментарии:
using System; using System.Collections.Generic; using System.Linq; using System.Text; namespace ConsoleApplication1 < /// /// Класс Program /// основной класс программы /// выводящий текст «Hello, World!» /// class Program < /// /// Метод Main() является /// входной точкой работы программы /// /// Аргумент метода Main() static void Main(string[] args) < // Форматируем шапку программы Console.BackgroundColor = ConsoleColor.Green; Console.ForegroundColor = ConsoleColor.Black; Console.WriteLine(«********************»); Console.WriteLine(«**** Мой проект ****»); Console.WriteLine(«********************»); // Основная программа Console.BackgroundColor = ConsoleColor.Black; Console.ForegroundColor = ConsoleColor.Green; Console.WriteLine(); Console.WriteLine(«Hello, World!»); // Ожидание нажатия клавиши Enter перед завершением работы Console.ReadLine(); >> >
Компилятор C# может извлекать XML-элементы из специальных комментариев и использовать их для генерации файлов XML. Чтобы заставить компилятор сгенерировать XML-документацию для сборки, указывается опция /doc вместе с именем файла, который должен быть создан:
csc /t:library /doc:MyApplication.xml MyApplication.cs
Данная команда сгенерирует файл XML по имени MyApplication.xml со следующим содержимым:
Program Класс Program основной класс программы выводящий текст «Hello, World!» Метод Main() является входной точкой работы программы Аргумент метода Main()
Обратите внимание на то, что компилятор на самом деле выполнил некоторую работу за вас: он создал элемент и также добавил элементы для каждого члена класса в этом файле. Каждый элемент имеет атрибут name с полным именем члена, снабженным префиксом — буквой, который указывает на то, является он типом (Т:), полем (F:) или членом (М:).
Источник: professorweb.ru