Unified documentation Frontend + Backend

[makspll]

Ideally we could have a unified documentation data definition language, which would describe the provided API for a provider.

We could then have different frontends which interpret that data for a target language.

As an example:

• Lua provider exports global "world" which is of the kind "Wrapper" around the type "bevy::ecs::World"
• It provides a method called "get_type_name" which accepts a String argument
• It generates a definition for it:

  {
  "id": "1"
  "kind": "global",
  "type_kind": "Wrapper",
  "type": "bevy::ecs::World",
  "functions": [
  {
    "name": "get_type_name"
    "args": [
      {
       "type_kind": "Primitive",
       "type": "String"
      } 
    ]
  }
  ]
  }

  • this definition is then interpreted by a LuaHTMLFrontend
  • Knowing how wrappers and primitives are handled in the Lua case, the generator produces html docs including a page for the world item
  • If the provider cannot express a certain type, it can fall back on some sort of plain default description (but this shouldn't happen, for compatibile backends and frontends)
  • This can be done at compile time thanks to bevy_api_gen, we can search the codebase for either custom attributes to generate the doc definitions, and they can also be produced manually for hand-written types