created: 20230318160840043 modified: 20230325162525198 tags: [[Reference Tiddlers]] title: Widget Documentation Style Guide Widget documentation generally consists of * an introductory summary of the widget's function * an overview of attributes and how the widget content is handled * more detailed attribute explanation when required * examples The //Content and Attributes// section should describe how the content of the widget is used, followed by a table of the possible attributes, each with a short description of a single sentence. The attribute names in the table and elsewhere in the tiddler should be rendered with the <<.var .attr>> macro. The <<.var .from-version>> macro should be used as first item in the description to designate the version at which a parameter became available. A subsection should be used for parameters that need an //extended description//, possibly with separate examples. When there are more than 2 such subsection necessary, the subsections should be split into their own tiddlers, and the <<.var .doc-tabs>> macro should be used to transclude them into the widget documentation tiddler as tabs. * The <<.var .doc-tabs>> macro is used without parameters * The <<.var .doc-tabs>> macro must not be used more than once within a single documentation tiddler * The tiddlers to be included in the tab group should be tagged with the respective widget documentation tiddler and have a <<.field description>> field set to <<.value tab>> * The <<.field caption>> contains the tab button text. It should be as short as possible. For the attribute name, the <<.var .attr>> macro should be used in the <<.field caption>> * The tab tiddlers should start with a level-2-heading that links to itself, so that they may be opened from within the tabs * They can contain examples if these are specific to the topic of the subsection In the attribute table, the <<.var .widget-attr-link>> macro can be used to turn attributes into a button that activates the respective tab. The <<.var .widget-attr-link>> macro is used like this ``` <<.widget-attr-link text: target: >> ``` Elsewhere, the <<.var .doc-tab-link>> macro can be used to activate the respective tab ``` <<.doc-tab-link text:<display text> target:<title of corresponding tiddler> tooltip:<tooltip to show when hovering over the button> class:<additional classes> >> ``` The parameters <<.param tooltip>> and <<.param class>> are optional. Both link macros scroll to the tab group additionally to setting the selected tab. They can also be used within the tab contents tiddlers themselves. If a tab tiddler is opened outside the tab group, <<.var doc-tab-link>> will open the tiddler containing the tab group if it is not yet open, and scroll to its tab group if it is.