Природные документы

Природные документы
Оригинальный автор(ы)	Грег Вэлью
Стабильная версия	2.3 / 11 сентября 2023 г.
Репозиторий	github .с /NaturalDocs /NaturalDocs ;
Написано в	C# ( Perl до версии 2.0)
Операционная система	Кросс-платформенный
Тип	Генератор документации
Лицензия	АГПЛ
Веб-сайт	NaturalDocs.org

Natural Docs — многоязычный генератор документации . Он написан на C# и доступен как бесплатное программное обеспечение на условиях AGPL . Он пытается сделать комментарии, написанные в исходном коде, такими же читабельными, как и сгенерированная документация. Он написан и поддерживается Грегом Валюром.

Фон

Теоретически Natural Docs может генерировать документацию на любом языке, поддерживающем комментарии, или из обычных текстовых файлов. При выполнении он может автоматически документировать функции, переменные, классы и наследование от ActionScript , C# и Perl независимо от существующей документации в исходном коде. На всех других языках их необходимо явно задокументировать, чтобы их можно было сгенерировать. Он может генерировать документацию в формате HTML как с фреймами, так и без них.

В отличие от Javadoc , он не считается отраслевым стандартом для документирования на каком-либо языке, хотя может включать документацию Javadoc для языков с «полной поддержкой». ^[2] Его используют некоторые любители и компании, такие как CNET Networks, Inc. и Iron Realms Entertainment . ^[3]^[4] Он приобрел популярность среди разработчиков ActionScript , поскольку не существует другого бесплатного генератора документации, который полностью поддерживал бы ActionScript, и поскольку он генерирует выходные данные более высокого качества, чем аналогичные генераторы, частично поддерживающие этот язык, такие как ROBODoc .

Пример

Это пример стиля документации:

 /*
  * Function: Multiply
  * 
  * Multiplies two integers.
  *
  * Parameters:
  *    x - The first integer.
  *    y - The second integer.
  *
  * Returns:
  *    The two integers multiplied together.
  *
  * See Also:
  *    <Divide>
  */
 
 int Multiply (int x, int y)
    {  return x * y;  }

Для сравнения, вот как то же самое будет документировано в Javadoc :

 /** 	 
  * Multiplies two integers. 	 
  * 	 
  * @param x The first integer. 	 
  * @param y The second integer. 	 
  * @return The two integers multiplied together. 	 
  * @see Divide 	 
  */ 	 
 
 int Multiply (int x, int y) 	 
    { return x * y; }

См. также

Сравнение генераторов документации

Примечания и ссылки

^ О натуральных документах
^ Языки естественной документации
^ Глобальная структура CNET от CNET Networks, Inc. и документация, созданная с использованием Natural Docs.
^ Rapture от Iron Realms Entertainment и документация, созданная с использованием Natural Docs.

Дальнейшее чтение

[1] О натуральных документах

[2] Языки естественной документации

[3] Глобальная структура CNET от CNET Networks, Inc. и документация, созданная с использованием Natural Docs.

[4] Rapture от Iron Realms Entertainment и документация, созданная с использованием Natural Docs.

[1]

[2]

[3]

[4]