Typal Methods

With Typal, a package that facilitates management of types in external files, methods are defined using XML schema. Documentary works together with Typal to embed the descriptions of methods into the documentation.

On This Page

• On This Page
• <typedef> Component For README
  • async runSoftware(path, config=): string
    • _namespace.Config
  • Flags
• Source Code
• Designs

<typedef> Component For README

Keeping types in a separate file not only allows to embed them into documentation, but also into the source code using Typal's template feature. This is needed when packages are compiled using Closure Compiler, and the JSDoc annotations are lost after compilation. Using the templates and information about methods, it becomes possible to restore editor run-time JSDoc for package consumers.

For example, a method can be defined in the following way:

<types ns="_namespace">
  <method async name="runSoftware" return="string">
    <arg string name="path">The path to the file.</arg>
    <arg opt type="_namespace.Config" name="config">
      The configuration object.
    </arg>
    This function will run the software, and return results.
  </method>

  <type name="Config" desc="The config for the program.">
    <prop name="View" type="Container">
      The view component connected to the store.
    </prop>
    <prop name="actions" type="Object">
      Possible actions for the reducer.
    </prop>
    <prop boolean name="static" opt>
      Whether to render the page as HTML file.
    </prop>
    <fn name="render" return="string">
      <arg name="component" type="Container">
        The JSX component to render.
      </arg>
      The renderning function.
    </fn>
  </type>
</types>

And it can be placed into the source code using the <typedef> component:

<typedef narrow level="3">wiki/Typal-Methods/api.xml</typedef>

The types found inside of the XML file(s) will be linked across the full compiled documentation, either a single README file, or multiple Wiki pages.

Example Of Method Embed

async runSoftware(   path: string,   config=: _namespace.Config, ): string This function will run the software, and return results. path* string: The path to the file. config _namespace.Config (optional): The configuration object. _namespace.Config: The config for the program. Name Type & Description View* Container The view component connected to the store. actions* Object Possible actions for the reducer. static boolean Whether to render the page as HTML file. render* (component: Container) => string The renderning function. component* Container: The JSX component to render.

Flags

There are some properties that can be passed to the typedef component:

• noArgTypesInToc: Don't print types of arguments in the table of contents.
• slimFunctions: Don't print arguments' description and types in the types' tables.

Source Code

The same type can be placed into the source code by creating a template.

The template uses the @methodType marker to indicate the type of the method.

const _runSoftware = require('./depack') /** * @methodType {_namespace.runSoftware} */ function runSoftware() { }

Typal then parses the types file, and updates the template to place annotations into the compiled file. Command used: typal template.js -T output.js -t api.xml.

const _runSoftware = require('./depack') /** * This function will run the software, and return results. * @param {string} path The path to the file. * @param {_namespace.Config=} [config] The configuration object. * @return {Promise<string>} */ function runSoftware() { }

Designs

To provide custom designs of headings for methods, follow this guide.

TODO: implement custom designs of descriptions and tables.