Talk:Documentation Format

Data Editor Documentation Format

I've been working on the documentation for some data editor fields. So far they're all for CEffectDamage but I plan on doing (much) more in the future. And basically before I get too far I want to have some kind of standard to use for the doc pages. For an example of the format I've been using see Death (CEffectDamage). Basically the pages consist of a (very) short blurb about the field at the top (right now it's just the name of the field, whether it's a field or an array, and the object type to which it belongs), followed by a documentation section that uses the documentation template.

After some thought, the standard for these documentation pages I'm proposing looks something like this:

PAGE NAME

The page name consists of the common name of the field followed by the object type to which it belongs in parentheses. For example, the page for the field Amount in CEffectDamage would be titled Amount (CEffectDamage) while the field Duration in CBehavior would be titled Duration (CBehavior).

DOCUMENTATION

The documentation on each field would consist of:

• the common name of the field (as it appears in the Data Editor).
• the object type in which the field can be found.
• the fully-qualified name. This is the name containing the full path to the field as specified in the xml files. In other words, this is the string you would use in the Game Catalog triggers to access the field. The difference is that the outermost object type to which the field belongs is appended as a prefix, separated from the rest of the path by a period ('.'). If the field or any object in the path is an array, they must be declared as such with an open and close parentheses ('[]') after the name of the array. For example, Amount in CEffectDamage would have a fully-qualified name of CEffectDamage.Amount while the Arc field in the Area array of CEffectDamage would have a fully-qualified name of CEffectDamage.AreaArray[].Arc.
• the type of data held by the field (while technically all data is stored in the xml files as strings, use the type naturally associated with the field in question. For example Duration in CBehavior would be a fixed.
• the range or set of accepted values that the field can have.
• the default value of the field.
• a description of the field. Special cases, especially ones that break the Principle of Least Surprise, should be described clearly here.

INDICES

If the field is an array with indices that do different things, a list of those indices is provided with a description on what each index does. (See Flags (CEffectDamage) for an example).

MEMBERS

If the field is itself a struct (or an array of structs) with members of its own, a list of the members is provided with documentation for each. (See Area (CEffectDamage) for an example).

ADDITIONAL INFORMATION

Additional information that doesn't fit into any of the sections mentioned above (such as bugs) may be supplied on the documentation page in separate sections on a case-by-case basis at the editor's discretion. These sections should be added at the end of the page.

INHERITANCE RESOLUTION

Fields that are inherited by a derived object type from a parent type should not have their documentation pages duplicated for the derived object type unless the inherited field has a different behavior in the derived type.

While I have been using this template for documentations, I propose switching to this one. An example of the new template in action is found here. The description goes into the main body of the page with the infobox on the right.

Any input on this is appreciated.

--Wangbot 21:30, 30 November 2010 (PST)