Skip to content

Documenting Components

Overview

Documenting a component makes it easier for others — and your future self — to understand what it does, how to configure it, and what each of its exported properties and declarations are for. Bellini supports documentation at three levels: the component itself, its declarations, and individual UI elements.

Good documentation is especially important for global components, which are shared across all applications in the organization and may be used by developers who did not build them.

When To Use This

Prioritize documentation when:

  • A component will be reused across multiple applications or by multiple developers
  • An exported property or function has non-obvious behaviour or expected values
  • A declaration or UI element has logic that cannot be inferred from its name alone

Component Description and Version

Each component has a description and a version that can be set via the Configure dialog.

To open the Configure dialog:

  1. Right-click the component in the Apps view or Components view.
  2. Select Configure. It opens the component configuration editor.

The configuration editor has two fields:

Field Description
Version A version label for the component (e.g. 1.0.0). Useful for tracking changes to shared global components.
Description A plain-text or Markdown description of what the component does, its intended use, and any relevant notes.

The description is displayed as a tooltip when the component is hovered in the Apps view or Components view, making it immediately visible to anyone browsing the component list.

Documenting Declarations

Individual declarations — properties, arrays, and functions — can each be given a description. This applies to all declaration types, but it is particularly important for exported declarations.

The description of an exported property or function is shown as a tooltip in the Properties view when the component is used on a page or inside another component. This gives the developer consuming the component the context they need to configure it correctly without opening the component editor.

To add a description to a declaration, either:

  • Enter the description in the Add Declaration dialog when creating the declaration, or
  • Right-click an existing declaration in the Declarations panel and select Configure Declaration.

Inline UI Comments

Individual elements on the canvas can be annotated with comments. To add a comment to a UI element:

  1. Select the element on the canvas or in the Elements Tree.
  2. Right-click and select Edit Comments.
  3. Enter the comment text.

Inline comments are most useful for describing specific rendering logic, conditional behaviour, or non-obvious structural choices that cannot be inferred from the element's type or name alone.

Documentation Best Practices

Documentation should complement the code, not substitute for clear naming and structure. Follow these guidelines to get the most value from Bellini's documentation features:

  • Name things clearly first. A well-named declaration or element often needs no description at all. Use descriptive names for declarations (e.g. selectedUserId rather than val) and keep the component hierarchy logically organized in the Elements Tree.
  • Document exported declarations thoroughly. Consumers of your component rely on the Properties view tooltip to understand what each exported property expects. Always add a description for exported declarations.
  • Use descriptions for non-obvious behaviour. Reserve inline UI comments and declaration descriptions for cases where the name alone is not enough — for example, a property that expects a specific format, or a function that has side effects.
  • Keep the component description up to date. When a global component changes significantly, update the description and bump the version so consumers know something has changed.

Helpful Resources