Tables for Game Data Files (Don't Accept PR) – v2

[MoltonMontro]

I think it's a good step - it looks nicer - but they are quite dense.

As a point of reference, it looks like Godot's docs use tables with word wrapping, but the table entries link to the full description below. https://docs.godotengine.org/en/stable/classes/class_node.html

They also have horizontal dividers between each full property description. Overkill for us?

For the sake of previewing, maybe worth adding the custom CSS to your commit? I experimented with this in a local build and it seemed to work: https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html

Revisions made based on the previous feedback/ideas, including word-wrapping. I've added tables to more docs, to help visualize how this'll look. Note that our property descriptions are just Lv.4 headers – Godot and RTD both use custom styling for similar info instead.

• GunAsset: unchanged.

• Intro to Items: removed the table names/captions.

• GripAsset: descriptions removed from table (only has one property) – they're now in a new "Property Descriptions" section.

• TacticalAsset: same as above, with more properties.

• MagazineAsset: same as above, with a lot of properties – including some with conditional default values. I think including the horizontal dividers might be helpful to break up the text. This table also includes links to property descriptions.

• SightAsset: same as TacticalAsset, but includes a list of dictionaries. I am unsure how dictionaries should be documented with this tabular format. Maybe dictionaries would just have a second properties table, and second description section?

• BarrelAsset: same as TacticalAsset, but horizontal dividers are between each full property description.

[MoltonMontro]

@SDGNelson RTD is building again (I think GitHub had a temporary outage). Check my first comment for the changes -- I've bolded the docs with the most notable ones.

[SDGNelson]

Opened the PR expecting to still need to investigate why the builds weren't working. Glad that it resolved itself!

Good idea trying a few things out in different files for comparisons.

• I personally like the table with links to the extended property descriptions.
• I think it would be good to include column headers ("Property Name", "Type", "Default Value"?)
• The horizontal dividers in Barrel Assets look good to me and help break up the dense text.
• I agree the dictionaries in Sight Assets should have their own secondary table and secondary description list.
• I think the = in property descriptions might be confusing to newcomers, perhaps suggesting that = should be included. Considering that some types have links (e.g., GUID) maybe we could add a types list and link to them? Then each part of the title would be easy to quickly read each part like Property Name Type Default Value? ID uint16 0

[MoltonMontro]

@SDGNelson Done (x5). I've updated all the previous docs + added new ones. Here's the list:

• C# Built-in Types
• Flag
• ELightingVision
• Introduction to Items
• Gun Assets
• Barrel Assets
• Grip Assets
• Magazine Assets
• Sight Assets
• Tactical Assets

---

Main exception is for Intro/GunAsset, which now more closely match the previous revision. A single table for all properties, with a separate section for property descriptions. These docs are exceptionally lengthy. For one of them, I moved Unity Setup info back to the top, and I agree that it seems better than having it below.

SightAsset is a good doc to view. It has three tables: Properties, DistanceMarker Dictionary, and ESide Enumeration. We discussed having docs for enums used by multiple classes, but maybe it should be for any with their own file? In this case, ELightingVision would have a doc, but ESide wouldn't.

Some thoughts about how we describe defaults and data types.

• I've labeled DistanceMarkers as a "list of DistanceMarker" type. Is there a better way to describe a data type like this? There's a few properties that are lists of XYZ.
• Properties like Explosion have two acceptable data types: GUID (32-digit hexadecimal) and uint16 (legacy ID). Is there a better way to label these, besides just listing both options?
• Some properties don't have a default (notably, flags) don't have default value. I've listed some as n/a, but I think leaving it blank may look better.
• Some properties have conditional default values. I've listed some as See description, but maybe these should be left blank?

I've added C# Built-in Types. We could create a doc per built-in type, but I don't believe it’s necessary.

Some "custom" data types are located in Data File Format. Any thoughts on moving Color, Flag, and Vector3 into their own docs instead?

If we plan to doc every Enum, maybe those (+PlayerSpotLightConfig?) should be nested into a folder in the TOC/index.

[SDGNelson]

You're fast!

• The gun asset property list is indeed quite lengthy. It would be nice to group some properties together like how it used to be and others sorted alphabetically, but hard to draw a line of how to separate them. Perhaps all of the property descriptions stay sorted alphabetically, but the property table can be grouped into tables of related properties? For example, a "Recoil" heading with all of the recoil-related properties sorted alphabetically?
• I agree that a single doc for all the c# built-in types would be sufficient rather than a doc for each type.
• Whether an enum has its own file is kind of arbitrary in the codebase. In the past I would often put them in their own file, whereas nowadays I tend to put them alongside their primary use (if applicable). I think the benefit of having a separate doc for enums would primarily be for updating them with new entries, so I think it makes sense to use in cases where multiple docs need the full list. For example, EUseable only needs the full list in the base ItemAsset, whereas the full ELightingVision list is needed in multiple places.
• As a minor nitpick to the above: I think the "Enumerator" column for the enums should be renamed to "Name".
• I think the way you labeled DistanceMarkers is good and clear.
• The GUID or ID label as you have it there looks good to me.
• Leaving the flag default blank sounds good. And I think the "See description" label is good to indicate it does have a default.
• Moving Vector3, Color, etc into their own docs for linking to from the property line? With your suggestion of having a folder for simple data types I agree that would fit well.