SDoc и документация на двух языках (Рус, Англ). Как реализовать?

[FINoM]

Задал такой же вопрос на тостере, надеюсь и здесь получить ответ.
Есть задача написания двух версий документации для кода: на английском и на русском. Ведение двух версий проекта и их синхронизация затруднительна. Я знаю, что такого нет из коробки в JSDoc, но, возможно, у кого-то есть идеи для хаков. Я представляю себе "язык", как дополнительный кастомный тег:

...
/**
@doclang rus
@method f
@desc Крутой метод 

@doclang eng
@method f
@desc Awesome method
*/
f: function() { /* ... */},
...

Спасибо.

[WorM32]

Кому нужны русские доки? Смысла ведь в этом нет никакого.

[kobezzza]

Лучшим решением будет парсить JSDoc и локализовывать комментарии по заданному JSON, а вообще это геморой, т.к. простое поддерженаие комментариев в актуальном виде сложно, а в ещё на разныз языках совсем ад

Кому нужны русские доки? Смысла ведь в этом нет никакого.

Доки нужны для разработчика. Я вот, например, не достаточно знаю инглишь, чтобы писать нормальные доки, а делать "огрызки" смысла нет, поэтому всё делаю на русском.

[FINoM]

Я не зацикливаюсь на JSDoc, меня волнует только одно: как сделать документацию на двух языках, но не прописывать её в статичных HTML файлах, чтоб можно было легко изменить шаблон вывода: HTML, JSON или в другую форму. Дошло до того, что я задумался написать собственный движок документирования вне JS файлов.

<method name="f" class="ClassName" lang="en">
	<sum>
		This method is very cool
	</sum>
	<desc>
		Big description
	</desc>
	<arguments>
		<argument name="x" optional="optional" default="12">
			Cool argument 1
		</argument>
		<argument name="y" repeatable="repeatable">
			Cool argument 2
		</argument>
	</arguments>
	<examples>
		<example caption="Basic usage">
			alert( new ClassName().f() )
		</example>
	</examples>
</method>

<method name="f" class="ClassName" lang="ru">
	<sum>
		Крутой метод
	</sum>
	<desc>
		Большое описание
	</desc>
	<arguments>
		<argument name="x" optional="optional" default="12">
			Крутой аргумент 1
		</argument>
		<argument name="y" repeatable="repeatable">
			Крутой аргумент 2
		</argument>
	</arguments>
	<examples>
		<example caption="Базовое использование">
			alert( new ClassName().f() )
		</example>
	</examples>
</method>

Но XML очень избыточный язык, а JSON - бедный. Что делать, хз пока.

[Gozar]

Парсим файлы, создаем линки, выводим в таблицу: слева en справа ru, пишем недостающее. Тыкаем в постинг, по линкам заменяется на нужный язык и складируется в отдельную папку.

В итоге будет создан еще один проект в папке lang, с докой на нужном языке.

Нюансы и вариации додумай сам. Я бы сделал так, как описал выше. Это подобие сборщика (grunt, gulp...)

Таким образом можно хоть на 20 языках написать доку.

[FINoM]

Я склоняюсь к другой мысли: использовать тот же JSDoc, с темплейтом haruki, который экспортирует доки в JSON. Файл publish.js достаточно прост, чтоб его модифицировать и реализовать кастомные теги. После экспорта в JSON, скормить его самописному шаблонизатору-генератору страниц. Сами доки вынести в отдельный JS файл.

/**
@lang en
@function f
@summary cool function
@desc description
@param {integer} x - my X
@param {string} [y] - my Y
*/

Такое решение решит несколько проблем:
- Удобный и неизбыточный синтаксис остаётся, не нужно мудрить с XML и другими форматами описания данных.
- Уйдет бардак в коде. Больше половины кода сейчас занимает документация. С новыми языками будет еще больше бардака.
- Файл с доками можно будет подключать отдельно в IDE, так как, в основном, либа будет использоваться в минифицированном виде. Причем, можно будет подключить доки на любом языке, а написать новую локализацию не составит труда: копируй файл и переводи.

Нерешенные проблемы:
- Нужно постоянно следить за соответствием документаций: поменялся аргумент или пример, нужно изменить доки ко всем языкам.
- Не понятно, в каком месте (в каком файле и строке) описан метод. Со старым способом в сгенерированной HTML документации всегда было понятно, где найти реализацию метода. Возможно, для решения этой проблемы есть какой-то тег.
- Не работают теги @link
- Персер Харуки не обрабатывает определние типов

[FINoM]

Парсим файлы, создаем линки, выводим в таблицу: слева en справа ru, пишем недостающее.

С таблицей крутая идея, спасибо, подумаю. Будет меньше гемора с синхронизацией.

[Gozar]

Нужно постоянно следить за соответствием документаций: поменялся аргумент или пример, нужно изменить доки ко всем языкам.

Это по любому придется делать, т.к. идея обязывает. Можно особо не следить, запускать парсинг по крону или другому планировщику, тот выдает уведомление. Можно даже прикрутить переводчик, но он скорее всего будет кривой.

Чем меньше промежуточных звеньев и конвертаций, тем целостней данные.

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

По сути тут ничего нового. Код - это тот же текст и поддается разбору и структурированию во что угодно.

Если линковка невозможна, то можно ставить свои линки id-шники. Лучше, конечно привязываться к названию метода, app.method.get, но и id тоже возможно, но их лучше генерить. В общем самое слабое место, это линковка. Если код не структурированный, то его нужно как-то линковать, т.к. методы могут переноситься, переназываться и т.д.