Difference between revisions of "User:Glyph"

From Kerbal Space Program Wiki
Jump to: navigation, search
(How to fix API templates)
Line 23: Line 23:
 
   
 
   
 
  // An enum that is NOT being displayed as a section on a class page, e.g. an enum on its own page.
 
  // An enum that is NOT being displayed as a section on a class page, e.g. an enum on its own page.
  Template:Enum
+
  Template:PageEnum
  |Template:EnumValue...  <- List of Template:EnumValue, without commas.
+
  |Template:PageEnumValue...  <- List of Template:PageEnumValue, without commas.
 
   
 
   
  // A value of a Template:Enum enumerations. Do not use this inside Template:ClassEnum, instead use Template:ClassEnumValue.
+
  // A value of a Template:PageEnum enumeration. Do not use this inside Template:Enum, instead use Template:EnumValue.
  Template:EnumValue
+
  Template:PageEnumValue
 
  |name=string
 
  |name=string
 
  |value=string|default blank
 
  |value=string|default blank
Line 37: Line 37:
 
   
 
   
 
  // Template for a list of enumerations that are part of a class.
 
  // Template for a list of enumerations that are part of a class.
  Template:ClassEnums
+
  Template:Enums
  |enums=Template:ClassEnum...  <- List of Template:ClassEnum, without commas.
+
  |enums=Template:Enum...  <- List of Template:Enum, without commas.
 
   
 
   
 
  // A section on a class page for enums belonging to that class.
 
  // A section on a class page for enums belonging to that class.
  Template:ClassEnum
+
  Template:Enum
 
  |name=string
 
  |name=string
  |values=Template:ClassEnumValue...  <- List of Template:ClassEnumValue, without commas.
+
  |values=Template:EnumValue...  <- List of Template:EnumValue, without commas.
 
   
 
   
  // A single enum value as part of ClassEnum. This is for enums on a class page, not enums on their own page.
+
  // A single enum value as part of Template:Enum. This is for enums on a class page, not enums on their own page.
  Template:ClassEnumValue
+
  Template:EnumValue
 
  |name=string
 
  |name=string
 
  |value=string|default blank  <- If this enum value is given an actual int value, specify that value here (without the =).
 
  |value=string|default blank  <- If this enum value is given an actual int value, specify that value here (without the =).

Revision as of 18:06, 15 October 2015

Things that need doing on the wiki

  • We could use a better Template:Type. Probably something that works recursively so we can have proper links to templated types e.g. Dictionary<String, Vessel> will properly link to Vessel.
  • Could use a template to stick at the top of API pages that urges users to contribute to the API descriptions.
  • Mark all pages in obsolete.
  • Add the Namespace:blah template to API pages.

API classes updated to KSP 1.04

Classes left to do

Error: infinite lists not supported

How to fix API templates

API templates are in a terrible state. None of their pages are clear in their intent or documentation, and the logic behind their structure does not work regardless. One of the biggest problems is generic types (link List<String>) and the solution for this, having an alternative Type template is not enough, because generic templates can be nested like Dictionary<String, List<String>>.

Here is a possible re-implementation using some tricks from EBNF (a language for specifying syntax).

// An enum that is NOT being displayed as a section on a class page, e.g. an enum on its own page.
Template:PageEnum
|Template:PageEnumValue...  <- List of Template:PageEnumValue, without commas.

// A value of a Template:PageEnum enumeration. Do not use this inside Template:Enum, instead use Template:EnumValue.
Template:PageEnumValue
|name=string
|value=string|default blank

// Used at the top of class pages.
Template:Class
|name=string
|summary=string|default blank

// Template for a list of enumerations that are part of a class.
Template:Enums
|enums=Template:Enum...  <- List of Template:Enum, without commas.

// A section on a class page for enums belonging to that class.
Template:Enum
|name=string
|values=Template:EnumValue...  <- List of Template:EnumValue, without commas.

// A single enum value as part of Template:Enum. This is for enums on a class page, not enums on their own page.
Template:EnumValue
|name=string
|value=string|default blank  <- If this enum value is given an actual int value, specify that value here (without the =).

// The Properties section of a class page.
Template:Properties
|properties=Template:Property...  <- List of Template:Property, without comma.

// A single property in a Template:Properties section of a class page.
Template:Property
|name=string
|type=Template:Type
|access=string  <- "public" or "protected"
|get=true|default blank
|set=true|default blank
|static=true|default blank
|summary=string|default blank

// The Fields section of a class page.
Template:Fields
|fields=Template:Field...  <- List of Template:Field templates, no comma between them.

// A single field in a Template:Fields section of a class page.
Template:Field
|name=string
|type=Template:Type
|access=string  <- "public" or "protected"
|static=true|default blank
|const=true|default blank
|initialValue=string|default blank
|summary=string|default blank

// The Methods section of a class page.
Template:Methods
|methods=Template:Method...  <- List of Template:Method templates, no comma between them.

// A single method in a Template:Methods section of a class page.
Template:Method
|name=string
|returnType=Template:Type|blank  <- blank for constructor
|access=string  <- "public" or "protected"
|static=true|default blank
|virtual=true|default blank
|args=Template:Arg, ...  <- Comma separated list of Template:Arg. Actually separated by ", " (comma and a space).
|summary=string|default blank

// A single method argument.
Template:Arg
|name=string
|type=Template:Type
|defaultValue=string|default blank  <- The default value for this argument, i.e. this is an optional argument.
|ref=ref|out|default blank  <- If this argument is a "ref" or "out" argument, or blank for neither.

// A type (class) and its generics, if any.
Template:Type
|name=string  <- The actual identifier for the type. List<Dictionary<Blah, Blah>> has the name List.
                 This, and nothing else, is linked to other pages via API:{name}.
|array=true|default blank  <- If set true, end type with [].
|generic=Template:Generic|default blank  <- If blank, this type is simple. If not, this type uses a
                                            generics template e.g. List<int> would have Template:Generic(Template:Type(int)).

// A list of generic types, as part of a Template:Type.
Template:Generics
|types=Template:Type,...  <- All the types that this generic template has, comma separated.