Skip to content

Latest commit

 

History

History
76 lines (51 loc) · 4.08 KB

CONTRIBUTING.md

File metadata and controls

76 lines (51 loc) · 4.08 KB
Raw

Contributing

This documentation strives to not only be accurate, but consistent. It has many conventions to aid predictability and readability. These may be seen in the official documentation, but are not followed closely.

This document is meant as a guide to help you get started. If you are not sure on how to do something, check other sections of the documentation to see how it is done.

Basics

Markdown

The documentation is written in a superset of Markdown called MDX. This allows for the use of JSX in the documentation, which is used for endpoints, alert boxes, and more.

Endpoints are defined like so:

<RouteHeader method="GET" path="/users/@me" supportsAuditReason unauthenticated supportsOAuth2="scope">
  Get Current User
</RouteHeader>

Alert boxes are defined like so:

<Alert type="warn">
  This endpoint deletes Discord. Do not use it.
</Alert>

Formatting

Within tables:

  • Base types should be documented as snowflake, string, integer, or boolean. If the type is an object, it should be documented as foo object and foo should be linked to the object's documentation. If the type is an array, it should be documented as array[foo object] and foo should be linked to the object's documentation.
  • If a field can have multiple types, it should be documented as foo | bar | baz. The | must be escaped with a backslash (\|) in the table.
  • If a field is optional, it should be documented as foo?. If a field is nullable, the type should be documented as ?foo.
  • If a field is deprecated, it should be documented as foo **(deprecated)** (or ommited if unnecessary and not yet documented).
  • In descriptions, capitals should be used, but periods should not be used. Abbreviations like "ID", "SKU", "URL", etc. should always be capitalized. Descriptions such as "The ID of the user" are preferred over "User ID" or "The user's ID".
Invite Channel Structure
Field Type Description
id snowflake The ID of the channel
type integer The type of channel
name ^1^ ?string The name of the channel (1-100 characters)
recipients? array[partial user object] The recipients of the DM; only the username field is present
icon? ^1^ ^2^ ?string The DM's icon hash

^1^ Notes on fields are done using footnotes. The syntax for footnotes is ^n^ where n is the number of the footnote. The footnote itself is defined at the bottom of the table.

^2^ Please do not use asterisks (*) for footnotes!

Enums

Enums are used to define a set of constants. They are used in many places in the documentation, and should be defined at the end of their relevant object section like so:

If enums are used in multiple places, they should be defined by the most relevant section.

Visibility Type
Value Name Description
0 NONE Invisible to everyone except the user themselves
1 EVERYONE Visible to everyone

Note that Type is used, not Types like in the official documentation.

For enums that have strings as values, the name can be skipped like so:

Platform Type
Value Description
web Represents the web platform
mobile Represents a mobile platform
desktop Represents a desktop platform