Skip to content

XML‐Documentation Tooling

Jump to bottom
rpatters1 edited this page Nov 3, 2024 · 4 revisions

This wiki page is so we can brainstorm how to document the enigmaxml file in a good way.

Defining the problem

the enigmaxml file contains numerous undocumented objects that define a finale score. The purpose of documentation tooling is to provide a way to unify machine and human readable documentation of the xml schema. This document is broken into requirements, data options, tooling options.

last updated 11/3/2024, Chris Roode

Requirements

Below is an initial list of requirements proposed for this tool.

  • The tool shall generate a machine readable specification, and human readable documentation from the same source material.
  • The tool shall operate on a reasonable cross platform system configuration. (if you get the gist).

Requirements conversation:

CPR: Is this really all the tool needs to do? What else should it do?

Data Options

In early stages of planning, the data options need to be explored to find the best configuration of tooling for this job. Below are possible options, followed by discussion.

Data model options

  • DTD: Document Type Definition
  • XSD: XML Schema
  • JSON:
  • Computer Language Model: To clarify this idea. Instead of using existing static schema definition, use a language like javascript, python, or c/c++ to specify objects and data types. Then use a set of library functions to turn the objects into a specification.

Data Options Conversation

Tooling Options:

Probably the hardest part of this task is deciding on a tooling to automation the generation of documentation from a single model. The tooling options are heavily dependent on the Data Option chosen, and vice versa. It is also worth considering the longevity of dependencies when planning the tooling.

Tooling options:

  • JSDoc: https://jsdoc.app/ - JSDoc uses a standard doxygen comment format to allow for creation of documentation pages for a node project. It does require a good number of dependencies, and requires the source to be written in javascript however.
  • Webpack: https://webpack.js.org/ - Webpack is a flexible and well known transpiler for javascript. Still unsure on the ability of webpack to create XSD or DTD files.
  • Doxygen: https://doxygen.nl/ - Doxygen is great at generating an html site from c/c++ source code. There are also extensions for python and other languages. It may be that one could devise comments in an xsd to generate an html site from that.

Tooling Discussion

CPR: I can guess immediately that we are going to have to decide on the data format first before even considering a tooling option. I know I am a big fan of dynamic includes, so for example, we could enumerate over all the various types of entries, and create a meaningful collection of objects that makes sense in a music format, so the model is more readable.

Clone this wiki locally