Controller Wiki Style Guide - LiruJ/GuiCookie GitHub Wiki
The purpose of a controller wiki page is to describe how someone would use the class, as well as show and explain the properties, signals, children, and components used by the controller.
The layout of a controller wiki page is as follows, in this order:
- Overview
- Components
- Element Properties
- Properties
- Signals
- Functions
All of which should use h1. If any of these sections are not needed, then they can be removed, ensuring the overall order stays the same.
Each section should explain its topic as such:
This should explain what the controller is and what it is used for. A reader should be able to understand the purpose of the controller purely by reading the overview, and should not need to delve deeper into the page to gain that knowledge.
The overview section should not describe anything in detail.
This section should list the components used by controller. Each component listed should also state which initialisation function is used to obtain the component, if the component is optional, and the access of the component (protected, private, etc.). A reader should be able to read this section to determine how the controller will behave with a certain set of components, or if adding a specific component to an element will affect the controller.
The access modifier and initialisation function should be directly under the header of the component in that order, in italics, and linking to any used functions. The header itself should link to the page of the component, like so:
protected, OnCreated()
This is how the controller handles mouse events.
Note that if a component is a property, it should still be listed in this section but not listed in the properties section.
This section should list each element that a controller uses and stores in a property. If the element is not found as a child (either with or without a recursive search) of the controller, then the section must explain where it looks for the element. The goal of this section is to let the user know what elements are used by a controller and how.
Under the header of the element property, the element's type, the initialisation function used to obtain the element (if applicable), and the name used to find the element should be written out in that order and in italics. Any relevant information should also link to other pages on the wiki, like so:
Button, OnFullSetup(), "StartButton"
This is the button used to start the function.
This section should list each public property of the controller along with its type and purpose. It should be made clear if the property is able to be set publicly, as well as any consequences of doing so. The property's type should be directly under the header in italics, like so:
int
Gets or sets the value of this element, automatically updating the label.
This section should list each signal of the controller and explain when they are invoked. The type, if existent, should be within the header. This can be achieved with a backstroke \ before the < and > symbols, like so:
This is invoked immediately after the event happens.
This section should list each public and protected function of the controller, showing each function's input parameters, access modifiers, and return type. The access modifiers and return type should come immediately after the header in italics and in the same order as in the source code, like this example found here:
public, void
Resizes the handle so that it covers the range argument. For example; if the slider's minimum value is 0 and the maximum value is 2, and the given argument is 1, the handle will fill 50% of the slider bar.
The description of each function should describe its exact purpose and a general use case, it should help the user understand how to use the controller itself.