Difference between revisions of "User:Glyph"

From Kerbal Space Program Wiki
Jump to: navigation, search
(How to fix API templates)
Line 20: Line 20:
  
 
Here is a possible re-implementation using some tricks from EBNF (a language for specifying syntax).
 
Here is a possible re-implementation using some tricks from EBNF (a language for specifying syntax).
 
Template:Class
 
|name=string
 
|summary=string|default blank
 
 
   
 
   
 
  // 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.
Line 33: Line 29:
 
  |name=string
 
  |name=string
 
  |value=string|default blank
 
  |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 for a list of enumerations that are part of a class.
Line 38: Line 39:
 
  |enums=Template:ClassEnum...  <- List of Template:ClassEnum, without commas.
 
  |enums=Template:ClassEnum...  <- List of Template:ClassEnum, without commas.
 
   
 
   
 +
// A section on a class page for enums belonging to that class.
 
  Template:ClassEnum
 
  Template:ClassEnum
 
  |name=string
 
  |name=string
 
  |values=Template:ClassEnumValue...  <- List of Template:ClassEnumValue, without commas.
 
  |values=Template:ClassEnumValue...  <- List of Template:ClassEnumValue, without commas.
 
   
 
   
 +
// A single enum value as part of ClassEnum. This is for enums on a class page, not enums on their own page.
 
  Template:ClassEnumValue
 
  Template:ClassEnumValue
 
  |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 =).
 
   
 
   
 +
// The Properties section of a class page.
 
  Template:Properties
 
  Template:Properties
 
  |properties=Template:Property...  <- List of Template:Property, without comma.
 
  |properties=Template:Property...  <- List of Template:Property, without comma.
 
   
 
   
 +
// A single property in a Template:Properties section of a class page.
 
  Template:Property
 
  Template:Property
 
  |name=string
 
  |name=string
Line 58: Line 63:
 
  |summary=string|default blank
 
  |summary=string|default blank
 
   
 
   
 +
// The Fields section of a class page.
 
  Template:Fields
 
  Template:Fields
 
  |fields=Template:Field...  <- List of Template:Field templates, no comma between them.
 
  |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
 
  Template:Field
 
  |name=string
 
  |name=string
Line 70: Line 77:
 
  |summary=string|default blank
 
  |summary=string|default blank
 
   
 
   
 +
// The Methods section of a class page.
 
  Template:Methods
 
  Template:Methods
 
  |methods=Template:Method...  <- List of Template:Method templates, no comma between them.
 
  |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
 
  Template:Method
 
  |name=string
 
  |name=string
Line 82: Line 91:
 
  |summary=string|default blank
 
  |summary=string|default blank
 
   
 
   
 +
// A single method argument.
 
  Template:Arg
 
  Template:Arg
 
  |name=string
 
  |name=string
Line 88: Line 98:
 
  |ref=ref|out|default blank  <- If this argument is a "ref" or "out" argument, or blank for neither.
 
  |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
 
  Template:Type
 
  |name=string  <- The actual identifier for the type. List<Dictionary<Blah, Blah>> has the name List.
 
  |name=string  <- The actual identifier for the type. List<Dictionary<Blah, Blah>> has the name List.
Line 95: Line 106:
 
                                             generics template e.g. List<int> would have Template:Generic(Template:Type(int)).
 
                                             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
 
  Template:Generics
 
  |types=Template:Type,...  <- All the types that this generic template has, comma separated.
 
  |types=Template:Type,...  <- All the types that this generic template has, comma separated.

Revision as of 03:11, 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.

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:Enum
|Template:EnumValue...  <- List of Template:EnumValue, without commas.

// A value of a Template:Enum enumerations. Do not use this inside Template:ClassEnum, instead use Template:ClassEnumValue.
Template:EnumValue
|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:ClassEnums
|enums=Template:ClassEnum...  <- List of Template:ClassEnum, without commas.

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

// A single enum value as part of ClassEnum. This is for enums on a class page, not enums on their own page.
Template:ClassEnumValue
|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.