Ability to add form author comments to form definition

[ebruchez]

This is different from #2585, which is a runtime option.

(I thought we already had an issue about this but I can't find it right now.)

This issue is about adding documenting the form definition. The form author could document:

• the form itself
• individual form components such as fields, grids, sections
• calculations and other formulas
• services, actions, etc.
• workflow (various parts)

Essentially, everything the form author can add to a form definition should be comment-able.

This would be very valuable for large and complex form definitions. There is logic in some customer forms right now which was never documented and is hard to reverse-engineer. This would give some kind of incentive to form authors to document non-obvious things.

Form Builder could also produce a report of the fields and associated documentation (#4573). This could be of tremendous value, and would also be marketable as few tools have this kind of capability.

[ebruchez]

See also:

• Circular dependency detection for recalculation dependencies #3602
• Help form author debug formulas, references and dependencies #3693
• Consider "modes" in Form Builder #3914

[ebruchez]

As a first step, the Form Settings, or a separate "Form Documentation" dialog, should have a big rich text editor to edit general form definitions documentation.

The documentation would be stored in the metadata instance, or as a custom <fb:doc> element at an appropriate location in the form definition such as within the main <xf:model>.

It would make sense to standardize on an element like <fb:doc> which could be placed in the form definition next to each such element.

Alternatively, the doc could be located in a single location and use an attribute, like for, to identify what the documentation is for.

We could remove the doc at publish time, but since we want the ability to pull back published form definitions (#750), we should probably keep it. Form Runner can, and should, remove it at runtime.

[ebruchez]

Comments don't need to be localizable, at least initially.

[ebruchez]

For calculate, etc.: introduce child element:

<xf:calculate id="..." value="sum(...)">
    <fb:doc>This is a cool formula that sums the things.</fb:doc>
</xf:calculate>

Also check what to do for <xf:type id="...">xs:decimal</xf:type>.