Burnout Wiki:Contributor guide: Difference between revisions
Add basic format documentation info so people don't have to dig around the spec.
(Added general section and format documentation section. Moved relevant text to format documentation page.) |
(Add basic format documentation info so people don't have to dig around the spec.) |
||
| (2 intermediate revisions by the same user not shown) | |||
Line 17:
= Format documentation =
Asset formats are usually defined using tables. An overview of a known good template is provided here. These are not rules and the template can be modified to fit different formats in any way needed.
See the [[Format documentation guide | format documentation guide]] for details on how to document technical information on assets.▼
In general, documentation following the template should preferably:
* Contain the offset, length, type, and name of each field in a structure;
* Contain the name and value of an enumeration's option;
* Have objective descriptions when possible;
* Have any notable information in a comment; and
* Be complete, with no missing fields or skipped data, including typedefs.
More specifically, it should:
* Note padding by the description saying "Padding" and the type and name being blank;
* Mark unknown types and names with a question mark (?);
* Leave descriptions and comments blank when not used;
* Demarcate different parts of the format, e.g. each structure, by a header with its name above it so it appears in the TOC;
* Never mix bases unless something is obviously mixed, e.g. a max int value being present in an enumeration; and
* Always use hexadecimal unless documenting a non-flag enumeration or bitfield.
=== Example structure ===
{| class="wikitable"
! Offset !! Length !! Type !! Name !! Description !! Comments
|-
| 0x0 || 0x4 || int32_t || mExample || Example field for documentation guide || This is just an example
|-
| 0x4 || 0x4 || || || Padding ||
|-
| 0x8 || 0x8 || uint64_t || ? || ||
|}
=== Example enumeration ===
{| class="wikitable"
|-
! Name !! Value !! Comments
|-
| EXAMPLE_ENUM_ZERO || 0 || An example with the value 0.
|-
| EXAMPLE_ENUM_ONE || 1 || An example with the value 1.
|-
| ? || 2 ||
|-
| EXAMPLE_ENUM_FORCE_INT || 0x7FFFFFFF || Forces the enum to compile to a 32-bit int.
|}
▲See the [[Burnout Wiki:Format documentation
= Style =
* File extensions for file names from all Burnout games before Paradise should be written in uppercase, as the original casing is inconsistent, both between platforms and between files on the same platform.
** In cases where the file name contains a parameter, such as <code>EXPORT/VALUEDB/VEHICLEPHYSICS/%s.CFG</code>, leave the parameter string - in this case, <code>%s</code> - with its original capitalisation.
* When adding a new build to the [[Prototype documentation
== Game names ==
| |||