Formatting type documents

[Anaminus]

Constructed types do not (yet) have generated information on their API, so they have to be described manually. This issue explores how type documents should be formatted to accommodate this.

Summary of options:

One decision for each option.

• Section headings (constructors, properties, functions, operators)
  • Markdown heading, ignore identification
  • Identify with non-standard bracket syntax
  • Identify with HTML heading
  • Code inline instead of heading
  • Code block instead of heading
• Section depth (constructors, properties, functions, operators)
  • Under Details
  • Top-level
• Parameter/return types
  • Require a type for every parameter
  • Adjacent parameters of the same type can be grouped together
• Constructor return types
  • Required
  • Omitted
• Show type variable (properties, functions)
  • Required
  • Omitted
• Property section name
  • Properties
  • Fields
• Function section name
  • Functions
  • Methods

Sample

Sample of a type document, with details of each option.

CFrame.md

# Summary
Describes a 3D position and orientation.

# Details
This section describes the type in detail.

## Constructors
This section lists the type's constructors, if applicable.

# Constructors
Possible alteration: Top-level sections. This would require extra logic from
rbxapiref, but may be cleaner in the long run.

### `CFrame.new(): CFrame`
Instead of C syntax, types use left-to-right (L2R) syntax. This may be adapted
later to match the syntax of the upcoming Typed Lua.

### `CFrame.new()`
Possible alteration: Omit the return type on constructors, since it should be
obvious what they return.

### `CFrame.new(): CFrame` {#ctor-empty}
Possible alteration: explicitly identify each constructor. This uses
non-standard markdown, but rbxapiref can render it. Requires coming up with a
name for each constructor.

<h3 id="ctor-empty"><code>CFrame.new(): CFrame</code></h3>

Possible alteration: Use literal headings to retain some compatibility with
other markdown parsers. May still have problems on some parsers. e.g. GitHub
produces permalinks from the content of the heading regardless of the `id`
attribute.

`CFrame.new()`

Possible alteration: Use code inline instead of heading.

	CFrame.new()

Possible alteration: Use code block instead of heading.

### `CFrame.new(position: Vector3): CFrame`
Description.

### `CFrame.new(position: Vector3, lookAt: Vector3): CFrame`
Description.

### `CFrame.new(x: number, y: number: z: number): CFrame`
Description.

### `CFrame.new(x: number, y: number, z: number, r00: number, r01: number, r02: number, r10: number, r11: number, r12: number, r20: number, r21: number, r22: number): CFrame`
Description.

### `CFrame.new(x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22: number): CFrame`
Possible alteration: Parameter grouping: unspecified parameter type has the next
specified type. Less verbose, but also less clear.

## Properties
This section lists the type's properties, if applicable.

## Fields
Possible alteration: Named "Fields" instead. Constructed types behave distinctly
from classes, so it's probably a good idea to use different terminology to
encourage this distinction.

### `CFrame.X: number`
Description

### `X: number`
Possible alteration: Exclude variable. Nothing to disambiguate. Less noisy, less redundant.

### `CFrame.Y: number`
Description.

### `CFrame.Z: number`
Description.

## Functions
This section lists the type's functions, if applicable.

## Methods
Possible alteration: Named "Methods" instead. See Fields.

## `CFrame:Inverse(): CFrame`
Description.

## `Inverse(): CFrame`
Possible alteration: Exclude variable.

## `CFrame:Lerp(goal: CFrame, alpha: number): CFrame`
Description.

## `CFrame:ToWorldSpace(): CFrame`
Description.

## `CFrame:GetComponents(): (x: number, y: number, z: number, r00: number, r01: number, r02: number, r10: number, r11: number, r12: number, r20: number, r21: number, r22: number)`
Description.

## `CFrame:GetComponents(): (x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22: number)`
Possible alteration: Grouped parameter types.

## Operators
This section lists the type's operators, if applicable.

### `CFrame * CFrame : CFrame`
Description.

### `CFrame * Vector3 : Vector3`
Description.

### `CFrame + Vector3 : CFrame`
Description.

### `CFrame - Vector3 : CFrame`
Description.

# Examples
This section provides usage examples of the type.

[Anaminus]

My current preferences:

• Bracket syntax for section headings.
• I'm willing to implement top-level sections in rbxapiref.
• While I would prefer to have grouped parameters, I understand that it's too obscure for unfamiliar readers.
• I prefer omitted return types on constructors.
• I'm fine with omitted variables on properties and functions.
• I prefer "fields" over "properties".
• I prefer "methods" over "functions'.

[Anaminus]

Identifier names

Constructors

The identifier begins with ctor- followed by the name of the constructor. If a constructor has multiple definitions, then a short, disambiguating description is appended. The first or least specific definition can omit the description.

### `CFrame.new()` {#ctor-new}
### `CFrame.new(position: Vector3)` {#ctor-new-position}
### `CFrame.new(position: Vector3, lookAt: Vector3)` {#ctor-new-look}
### `CFrame.new(x: number, y: number, z: number)` {#ctor-new-xyz}
### `CFrame.Angles(rx: number, ry: number, rz: number)` {#ctor-Angles}

Fields

The identifier begins with field- followed by the name of the field.

### `X: number` {#field-X}
### `Y: number` {#field-Y}
### `Z: number` {#field-Z}
### `Position: Vector3` {#field-Position}
### `LookVector: Vector3` {#field-LookVector}

Methods

The identifier begins with method- followed by the name of the method.

### `Inverse(): CFrame` {#method-Inverse}
### `Lerp(goal: CFrame, alpha: number): CFrame` {#method-Lerp}
### `ToWorldSpace(cf: CFrame): CFrame` {#method-ToWorldSpace}
### `ToObjectSpace(cf: CFrame): CFrame` {#method-ToObjectSpace}

Operators

The identifier begins with op- followed by the metamethod name, then the other operand, if applicable.

### `CFrame * CFrame : CFrame` {#op-mul-CFrame}
### `CFrame * Vector3 : Vector3` {#op-mul-Vector3}
### `CFrame + Vector3 : CFrame` {#op-add-Vector3}
### `CFrame - Vector3 : CFrame` {#op-sub-Vector3}

[Anaminus]

Automate identifier names

Parse headers in a particular way to generate an identifier automatically.

Constructors

• Prefer ctor-<name> when possible.
• To disambiguate, concatenate the name of each argument (ctor-new-position-lookAt).

Fields

• field-<name>

Methods

• method-<name>

Operators

• Type + Operand : Result becomes {#op-add-Operand}
• Type - Operand : Result becomes {#op-sub-Operand}
• Type * Operand : Result becomes {#op-mul-Operand}
• Type / Operand : Result becomes {#op-div-Operand}
• Type % Operand : Result becomes {#op-mod-Operand}
• Type ^ Operand : Result becomes {#op-pow-Operand}
• Type .. Operand : Result becomes {#op-concat-Operand}
• Type == Operand : Result becomes {#op-eq-Operand}
• Type < Operand : Result becomes {#op-lt-Operand}
• Type <= Operand : Result becomes {#op-le-Operand}
• -Type : Result becomes {#op-unm}
• #Type : Result becomes {#op-len}
• Type[Operand] : Result becomes {#op-index}
• Type[OperandA] = OperandB : Result becomes {#op-newindex}
• Type(Parameters) : Result becomes {#op-call}