User:Anaminus/API Documentation Changes

The following sections contain proposed changes to Roblox API documentation (e.g. Class Reference, RBX.lua.Instance (Object), etc).

To discuss changes to these proposals, use the talk page.

Page Name Conventions

This section proposes changes to the naming of pages involving API documentation.

To distinguish and separate API documentation from other pages, a namespace called "API" (or other chosen name) should be added.

Expand: Why do they need to be distinguished and separated?

The API namespace should have subpages enabled, so that member pages can utilize the feature.

Goals

• Move API pages out of the main namespace
• Disambiguate member pages
• Simplify naming conventions

Drawbacks

• Need to contact admin with access to wiki server

New naming conventions

A class in the API namespace:

API:Instance

• removed weird RBX.lua prefix; title is distinguished by API namespace
• removed (Object) suffix; was never necessary
• easy to use with page name variables (i.e. {{BASEPAGENAME}}) for automated linking

Members in the API namespace:

API:Instance/Clone
API:Instance/Name
API.Instance/Changed

• utilizes MediaWiki's subpages; more semantically correct; allows usage of page name variables (i.e. {{SUBPAGENAME}})
• removed (MemberType) suffix; title is disambiguated by API namespace and base page
• The first letter of subpages are case-sensitive (remove and Remove are different)
• Members that share the same name, but belong to different classes, are properly separated

Other information

LocalSettings.php:

# API namespace define("NS_API", 200); #define NS_API variable at namespace index 200 define("NS_API_TALK", 201); #define NS_API_TALK variable for talk page $wgExtraNamespaces[NS_API] = "API"; #add the API namespace as the name "API" $wgExtraNamespaces[NS_API_TALK] = "API_talk"; #add the API talk namespace $wgNamespacesWithSubpages[NS_API] = true; #enable subpages for API $wgNamespacesWithSubpages[NS_API_TALK] = true; #enable subpages for API talk Note: Namespace indices 200 and 201 are registered by the SocialProfile extension, but it's unlikely that the Roblox Wiki will ever install it. Alternate indices can be chosen, as long as they don't conflict with other extensions that may be installed.

Page Content Conventions

The following subsections contain proposed changes to the content of pages involving API documentation.

Each section describes a basic outline for content of these pages. If an outline is agreed upon, then the actual appearance and structure can be discussed.

Object pages

The current implementation of object pages scatters the object's information across multiple pages, then trancludes it all into the one page. This is done for the purpose of automating the display of class inheritance. That is, so the object's page displays the members of the classes it inherits from. Unfortunately, this model introduces complications. Not only does it make editing the object's information difficult for writers, it creates a large overhead of cascading page transclusions, increasing the page's load time and workload to the server.

Goals

• Unify an object's information onto one page.
• Make object pages more simple to create and edit.
• Reduce load time by minimizing transclusions.

Drawbacks

• No more automated class inheritance.
  • This can be made up for by teaching users about inheritance.
• Overall structure of pages are no longer maintained by templates, which means that the structure of every page can no longer be changed with one edit.
  • If a well-thought-out structure is used, making global changes shouldn't be necessary. Appearance can be handled by CSS, as it should be.
• Obviously, every page will have to be rewritten to conform to the new model.

Object page outline

• An info box, which contains information about the class that is common to all classes;
  • the class's explorer icon
  • the class this class inherits from
  • whether the class is preliminary or deprecated
  • whether the class can be created with Instance.new
  • whether the class can be acquired with GetService
  • a relevant image, if applicable (right now this exists as filler, not sure if it's any good to have)
• A list of the class's subclasses
• Tables containing the unique* members of the class, separated by member type (method, property, event, callback). Each table contains,
  • a member icon, including whether it is protected or locked
  • a member name, linking to the member's page
  • a simple description; describing what it is without going into too much detail; ignores arguments, returns, types, parameters, etc, as they will be described on the member's page
• For each member type, a link to the superclass's members of the same type (emphasize inheritance)
• Noteworthy API differences, such as the class being structural
• Bugs, including member bugs
• Links to pages that are relevant to the class, such as tutorials
• If the class is apart of a series of similar classes, include those (probably as a navbox)

*Excludes inherited members. A strong indication of the class's superclass should be made

Mockup of possible layout: [1]

Member pages

While the current structure of member pages is fine, there is room for improvement. Part of simplifying the process of creating and editing pages is defining what the page should contain.

Goals

• Define a concrete outline for member pages

Member page outline

• An info box, containing information about the member. Such information can include:
  • An icon, with protection/lock indication
  • The member's type, arguments, parameters, etc
  • The class the member belongs to
  • Some kind of link to a page that explains the member's type (that is, method, property, event, etc)
  • Also, it should be possible to transclude the info box into other pages (for tutorials and whatnot)
• A detailed description, covering all of the member's arguments, parameters, etc (where applicable)
• Examples; ideally, these should actually be useful
• Bugs related to the member
• Links to other relevant pages

General disambiguation

When members of different classes share the same name, how should they be disambiguated?

Example: The "Changed" member occurs in many classes. How should the Changed page be handled?

1. Disambiguate: Page lists out all pages that need disambiguating
   • Great for many pages that need disambiguating
   • Annoying when there are only 2 or 3 pages
2. Redirect: Page redirects to the most commonly used page, where disambiguation will occur
   • Great for few pages
   • Bad for many pages
3. Mix of both: When there are only a few pages to disambiguate, use #2, when there are many, use #1
   • Great for few pages
   • Great for many pages