Как поддерживать документацию на предметно-ориентированном языке на основе JSON?

Мы разрабатываем язык описания игр, похожий на RPG. Раньше мы использовали уродливый низкоуровневый XML, но теперь мы переключились на высокоуровневый, почти удобочитаемый JSON (пока мы не выкатываем новый графический редактор и больше не нужно писать файлы вручную; хотя мы бы вероятно, оставьте его для низкоуровневого, быстрого и грязного авторинга). Движок игры написан на Java.

Как бы вы документировали формат файла JSON, который будет использоваться в Java?. У нас есть более 50 «типов объектов», от сцен до фонов, разговоров, переходов, предметов, персонажей и тому подобного. Мы хотели бы обновлять формат по мере добавления и настройки функций, поэтому важна простота обновления. В настоящее время некоторые биты JSON переводятся во множество битов Java, поэтому хорошей целью документации может быть модуль Java «JSON Reader», который выполняет этот перевод. Альтернативой может быть документирование какой-то «спецификации» формата JSON, которая может быть записана, например, в каком-то «JS API».

Некоторые из вещей, которые мы могли бы использовать:

  • jsDoc — мы можем документировать каждый тип объекта в JS, как параметры поддельного JS API.
  • старый добрый JavaDoc в исходном коде Java JSON-Reader; но JavaDoc не понимает JS, насколько мне известно; поэтому нам может понадобиться написать пользовательский документ JavaDoc. тег для наших тегов JS.
  • (ваше предложение здесь)

ПРИМЕЧАНИЕ: это не вопрос «какой инструмент лучше»; моя цель состоит только в том, чтобы найти один или несколько рабочих процессов документации-кандидатов для JSON, которые будут потребляться из-Java.


java json documentation-generation
person tucuxi    schedule 18.11.2013    source источник
comment
Вы предпочитаете использовать JSON, а не Java? Вы можете создать классы Java, которые вы можете задокументировать, которые на самом деле являются представлением вашего JSON (вы можете реализовать для него сериализацию из JSON). Вы также можете взглянуть на json-schema.org.   -  person zenbeni    schedule 18.11.2013
comment
Json-schema выглядит как очень хороший способ взаимодействия с обоими - спасибо, @zenbeni! Кажется, что мы можем задокументировать схему json и получить из нее заглушки Java, а также упростить нашу программу чтения JSON (и проверить ввод, что всегда хорошо). Можете ли вы повторно отправить ответ в качестве ответа, чтобы я мог проголосовать и в конечном итоге принять?   -  person tucuxi    schedule 18.11.2013

Ответы (1)


arrow_upward
4
arrow_downward

У вас есть два варианта:

  • Вы можете сосредоточиться на Java и определить классы Java, которые вы можете документировать, а затем сериализовать в JSON: Java-first.

  • Вы можете определить, что содержит ваш JSON, с помощью схемы (аналогично XML-схемам, которые используются с... маршаллингом XML): JSON-first. Его можно определить с помощью http://www.json-schema.org.

person zenbeni    schedule 18.11.2013
comment
Теперь мы используем json-schema с интеграцией Maven для создания наших классов Java на основе схемы, гарантируя всегда актуальную документацию. - person tucuxi; 23.11.2013