Implement comment-based type, function, method, and variable documentation (i.e. LuauDoc)

Feature Requests Studio Features
, , ,
4

Attaching docs to types would be important to carry over for overloaded functions too, i.e.

--- Create an identity Quaternion <0, 0, 0, 1>
type QuatIdentity = ()->Quaternion

--- Create a Quaternion from euler angles
-- @param rotRotation in radians
-- @param order Order of application of rotations
type QuatEuler = (rot: Vector3, order: Enum.RotationOrder?)->Quaternion

--- Create a Quaternion as a rotation about a global axis
-- @param axis Axis of rotation
-- @param angle Angle of rotation about axis
type QuatAxisAngle = (axis: Vector3, angle: number)->Quaternion

--- Create a Quaternion as a rotation facing toward {lookAt} from {pos}
-- @param pos Source position
-- @param lookAt Target position
-- @param upVec Optional UpVector
type QuatLookAt = (pos: Vector3, lookAt: Vector3, upVec: Vector3?)->Quaternion

--- Create a Quaternion from explicit <x,y,z,w> components
type QuatXYZW = (x: number, y: number, z: number, w: number)->Quaternion

--- Create a Quaternion representation of a CFrame
type QuatCFrame = (cframe: CFrame)->Quaternion

Quaternion.new = (
    function(...: any): Quaternion
        --....
    end 
)::(QuatIdentity & QuatEuler & QuatAxisAngle & QuatLookAt  & QuatXYZW & QuatCFrame)

--- Calculate the conjugate of a Quaternion
function Quaternion.Conjugate(self: Quaternion): Quaternion
    return Quaternion.new(-self.X, -self.Y, -self.Z, self.W)
end

--- Calculate the inverse of a Quaternion
function Quaternion.Inverse(self: Quaternion): Quaternion
    local len: number = self:MagnitudeSqr()
    return 
        if len == 0 then self
        else Quaternion.new(-self.X / len, -self.Y / len, -self.Z / len, self.W / len)
end

--- Length of a Quaternion
function Quaternion.Magnitude(self: Quaternion): Quaternion
    return math.sqrt(self.X^2 + self.Y^2 + self.Z^2 + self.w^2)
end

--- Length of a Quaternion squared (faster)
function Quaternion.MagnitudeSqr(self: Quaternion): Quaternion
    return self.X^2 + self.Y^2 + self.Z^2 + self.w^2
end

--- Returns a normalized Quaternion
function Quaternion.Unit(self: Quaternion): Quaternion
    local len: number = self:Magnitude()
    return Quaternion.new(self.X / len, self.Y / len, self.Z / len, self.W / len)
end

--- Identity Quaternion <0, 0, 0, 1>
Quaternion.identity = Quaternion.new()

type QuatInternal = {X: number, Y: number, Z: number, W: number}

--- [Quaternion](https://en.wikipedia.org/wiki/Quaternion)
-- 4D representation of arbitrary rotations
-- See [Quaternion.new()](Quaternion.new)
export type Quaternion = typeof(
    setmetatable(
        {} :: QuatInternal,
        Metatable
    )
)
2 Likes