Burnout Wiki:Format documentation specification: Difference between revisions
Burnout Wiki:Format documentation specification (view source)
Revision as of 07:16, 4 August 2023
, 9 months agoBurninrubber0 moved page Burnout Wiki:Format documentation guide to Burnout Wiki:Format documentation specification
(Added bit field information and some additional information.) |
m (Burninrubber0 moved page Burnout Wiki:Format documentation guide to Burnout Wiki:Format documentation specification) |
||
| (10 intermediate revisions by the same user not shown) | |||
Line 11:
== Unused columns ==
Columns defined here should never be removed, even when empty. This is a compromise between readability and editability; adding columns, especially in large tables, can be very tedious and time-consuming.
== Sections ==
Formats should be documented with at least the top-level section ''Structures''. ''
Generally, individual structures,
Sections should be named the full name of the type with all namespaces included, e.g., BrnVehicle::GraphicsSpec. If the full name is unknown, use a name relevant to its purpose. Never title a section "unknown" unless the content's purpose is truly unknown.
== Page names ==
Page names should be plain English versions of the official format name, e.g., the page for GenericRwacWaveContent is titled Generic RWAC Wave Content. If the format name is unknown, use a name most relevant to its purpose.
= Structures =
Line 42 ⟶ 47:
==== Type ====
The data type of the field. If the type is unknown, refer to [[#Choosing a data type
If the type is known and is a structure, union, enumeration, or custom typedef, this should be a link to the relevant section. If the official documentation states it is a standard type but it is still used as an enumerated value or similar, leave the link in the Comments column in the style "See <nowiki>[[link]]</nowiki>".
This column may be left blank if the area is known to be undefined (padding).
==== Name ====
The name of the field. This must be provided in some official capacity, such as source code, debugging symbols, or online documentation. If no official documentation is available, display a single question mark to mark it as unknown.
This column may be left blank if the area is known to be undefined (padding).
==== Description ====
A description of the field's meaning and/or purpose as defined by either official documentation, the user, or some combination of both.
User-defined types should not be described here; instead, they should be linked to from the Type column and described there. This column is solely for describing the field's use(s).
If nothing is known about the field, this column may be left blank.
==== Comments ====
Any comments about the field may be left here. This includes example values, whether the field has a constant value in all samples (such as it being null), and other speculation on it that does not fit the Description column. This is also where certain types, such as untyped enumerations, may be linked to in the style "See <nowiki>[[link]]</nowiki>".
If there are no additional comments, this column may be left blank.
= Unions =
Unions are types which use only one member at a time. They can be displayed similarly to structures but without the offset field.
{| class="wikitable"
|-
! Length !! Type !! Name !! Description !! Comments
|-
| 0x4 || uint32_t || mExampleInt || An integer member. || This is an example
|-
| 0x4 || float || mExampleFloat || A floating point member. || This is an example
|}
== Columns ==
==== Length ====
The length of the field. This should always be hexadecimal and prefixed with <code>0x</code>, even if the length is less than decimal 10. See [[#Length|Structures]] for more details.
The length should be defined per member just as it is with structures. The overall length of the type will be determined by its largest member and should not be listed separately.
==== Type ====
The data type of the field. If the type is unknown, refer to [[#Choosing a data type|choosing a data type]].
If the type is known and is a structure, union, enumeration, or custom typedef, this should be a link to the relevant section. If the official documentation states it is a standard type but it is still used as an enumerated value or similar, leave the link in the Comments column in the style "See <nowiki>[[link]]</nowiki>".
This column may be left blank if the area is known to be undefined (padding).
Line 66 ⟶ 113:
= Typedefs =
Typedefs are unique in that they can only be detected when some form of official documentation is available. This means there are no unknowns associated with them
Type definitions should be displayed in the following format:
{| class="wikitable"
|-
! Name !! Type !! Length !! Comments
|-
| ExampleType || int32_t || 0x4 || This is just an example
|}
Line 82 ⟶ 129:
==== Type ====
The type specifier used with the typedef.
==== Length ====
The length of the type in bytes. This should be a hexadecimal value prefixed with <code>0x</code>.
==== Comments ====
Line 94 ⟶ 144:
== Traditional enumerations ==
Most enumerations are sets of sequential values from which a single value may be used per variable. It follows that such enumerations are typically in decimal format, and wiki content should reflect this. Sometimes, however, it is appropriate to use hexadecimal, such as with how [[Resource Types
Enumerations should be displayed in the following format:
Line 138 ⟶ 188:
= Bit fields =
[https://en.wikipedia.org/wiki/Bit_field Bit fields] should be denoted in a similar manner to [[#Structures
{| class="wikitable"
Line 148 ⟶ 198:
== LSB 0 vs MSB 0 ==
As with [[#Binary flags
This solution used by the wiki is to display all binary structures in MSB 0 notation, even when official documentation has it in LSB 0. This improves consistency and readability.
Line 181 ⟶ 231:
! Bit value !! 0 !! 0 !! 0 !! 1 !! 0 !! 0 !! 0 !! 1 !! 1 !! 1 !! 1 !! 1 !! 1 !! 1 !! 0 !! 0
|-
| '''Parsed value''' || colspan=4
|-
| '''Description''' || colspan=4
|}
Line 190 ⟶ 240:
{| class="wikitable"
|-
! rowspan=3
|-
| colspan=4
|-
| colspan=4
|}
| |||