Provide Documentation

[ricardomatias]

Provide documentation with links to the source code and additional resources. This may allow users to find their way into the toolkit more easily.

Tasks

• Documentation can be found
• Documentation can be searched
• Documentation can be enriched with examples and external links
• Documentation caters towards different audiences (shallow integrators, customizers)
• Documentation separates public API from internals (TBD)
• Documentation is publicly accessible / linkeable via deep links
• Documentation is able to handle cross project boundaries (i.e. diagram-js ➕ bpmn-js)
• ...

See also 2021 assessment of our documentation.

---

Related to bpmn-io/diagram-js#78

Related to forum post

[nikku]

Examples for auto-generated documentation:

• JSDoc to HTML

Examples for custom-made documentation:

• Read the docs

Examples for mixed API docs + custom-made:

• Threejs docs

[bennypowers]

In addition to generating a docs site, please generate .d.ts typings from your JSDoc. This should be a relatively straightforward, publish-time step, although it would provide much value to users.

microsoft/TypeScript#32372

[nikku]

@bennypowers Thanks for the link.

Why would that be necessary? The TypeScript type checker does not consider JSDoc in node_modules?

[bennypowers]

unfortunately not :/

additionally, this could help you generate docs via typedoc (either as JSON to be fed into some other documentation engine, or as html)

[nikku]

Linked your idea here. Valuable input, thanks for sharing.

[nikku]

I've added my 2021 assessment on documentation to the issue description.

[lmihalkovic]

... so yes, tsc can generate typings from JSDoc. I created a small project to automatically generate them for diagram-js. As could be anticipated, the result is unusable: the doc is fine for someone who can infer the intentions of the developer (or understands well some typical JS coding patterns), or can read the source code to validate the interpretation, but in many places it is simply not precise enough in its current form.

simple example:

* @param {string} [name] the optional event name
* @param {Object} [event] the event object
* @param {...Object} additional arguments to be passed to the callback functions
EventBus.prototype.fire = function(type, data) {...}

The generator outputs

  fire(type: any, data: any, ...args: any[]): boolean;

This is plain wrong.

I will try to investigate why the generator does not output the slightly better

  fire(type?: any, data?: any, ...args: any[]): boolean;

The cleaner output would be something like:

  fire(name: string | { type: string }, event?: any, ...data: any[]): any;

This is truly a bummer as diagram-js is an otherwise nice piece of code ...

[philippfromme]

Closed in favor of https://github.com/bpmn-io/internal-docs/issues/683.

[nikku]

Shouldn't we keep a public issue open? Feel free to move it to backlog and unassign yourself.

[nikku]

As of bpmn-js@13 we offer comprehensive API documentation (via type definitions).