Действительно, JavaScript должен написать что-то вроде этого:
function example(x) {
"Here is a short doc what I do.";
// code of the function
}
Строка фактически ничего не делает. Есть ли причина, почему никто не должен комментировать свои функции в JavaScript таким образом?
Два момента, о которых я мог думать во время обсуждения вопроса:
Строковый литерал должен быть инициирован, что может быть дорогостоящим в долгосрочной перспективе
Строковый литерал не будет распознан как сменный JS minifiers
Любые другие точки?
Изменить: Почему я поднял эту тему: я нашел что-то вроде этого на John Resig Blog, где в новом стандарте ECMA 5 используется не назначенный строковый литерал, чтобы включить "строгий режим". Теперь мне было интересно просто оценить, могут ли быть использование или опасности при оформлении такой документации.
В Javascript действительно нет смысла делать это. В Python строка становится доступной как член __doc__ функции, класса или модуля. Таким образом, эти docstrings доступны для интроспекции и т.д.
Если вы создаете такие строки в Javascript, вы не получаете никакой пользы от использования комментария, а также получаете некоторые недостатки, такие как строка, всегда присутствующая.
Я искал способ добавить многострочные строки в свой код, не засоряя его \n. Похоже, что этот модуль соответствует счету: https://github.com/monolithed/ doc
К сожалению, комментарии не выживут, но я думаю, вы могли бы написать компилируемую задачу для преобразования docstrings в формат "\n".