openmrs / openmrs-esm-cli

Defunct. See https://github.com/openmrs/openmrs-esm-core/tree/master/packages/tooling
0 stars 3 forks source link

config-autodoc should generate documentation as JS config #8

Open brandones opened 4 years ago

brandones commented 4 years ago

The config documentation generator should, given a schema like

robots: {
  default: [
    { name: "R2-D2", homeworld: "Naboo" },
    { name: "C-3PO", homeworld: "Tatooine" }
  ],
  arrayElements: {
    name: {
      validators: [validator(n => /\d/.test(n), "robots must have numbers in their names")],
      description: "the robot's full name"
    },
    homeworld: {
      default: null,  // not required
      validators: [validators.isString],
      description: "the planet of origin, if known"
    }
  },
  validators: [validator(a => a.length > 0, "at least one robot is required")],
  description: "a list of the robots that will be operating on your ship"
}

produce documentation like this

"@openmrs/esm-robots": {
  "robots": [
    // a list of the robots that will be operating on your ship
    // at least one robot is required
    {
      "name": "R2-D2",  // required
        // the robot's full name
        // robots must have numbers in their names
      "homeworld": "Naboo"  // default: null
        // the planet of origin, if known
        // must be a string
     },
     { "name": "C-3PO", "homeworld": "Tatooine" }
  ]
}

Here's another example, this one with nesting and simple arrays.

"@openmrs/esm-hologram-doctor": {
  "hologram": {
    "color": true
      // whether the hologram supports color display
  },
  "virtualProvider": {
    // the care provider to be projected into the clinic
    "name": {
      "given": ["Qui", "Gon"]
        // any given names
        // each element must be a string
    }
  }
}
brandones commented 4 years ago

I think the above seems like a reasonable specification, but I am very open to other suggestions!