Существуют ли какие-то конкретные стандарты или названия для документирования конечных точек вашей библиотеки?

Question

Каждая библиотека, учебная или базовая документация, которую я видел в Интернете, имеет несколько синтаксисов псевдокодов для доступа к конечным точкам или функциональным возможностям, но иногда это не имеет никакого смысла. Есть ли для этого какой-либо стандарт?

Например chmod + x здесь имя файла заключено в <> этих символов, но при написании команды мы игнорируем <> эти, так же как и в руководстве разработчика mozilla, следующий синтаксис для функций стрелок javascript.

(param1, param2, …, paramN) => { statements } 
(param1, param2, …, paramN) => expression
// equivalent to: => { return expression; }

// Parentheses are optional when there's only one parameter name:
(singleParam) => { statements }
singleParam => { statements }

// The parameter list for a function with no parameters should be written with a pair of parentheses.
() => { statements }

Так есть ли определенные стандарты для такого рода типовой документации?

Answer 1

Существует спецификация JSDoc , которая определяет синтаксис документации, поддерживаемый большинством IDE (VisualStudio, WebStorm, NetBeans и т. Д.). Eclipse и Aptana поддерживают аналогичную спецификацию ScriptDoc .

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

Если документация написана от руки или документация содержится в комментариях к коду или в самодокументированных функциях, то строгого синтаксиса нет, но большинство разработчиков используют JSDoc, поскольку он поддерживается IDE.

Существует множество аналогичных спецификаций для других языков, например PHPDoc , и большинство из них основаны на JavaDoc , разработанном Sun для документирования классов и методов Java.