Difference between revisions of "User:Glyph"

From Kerbal Space Program Wiki
Jump to: navigation, search
(How to fix API templates)
(How to fix API templates)
 
(7 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
* Could use a template to stick at the top of API pages that urges users to contribute to the API descriptions.
 
* 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 [[Category:KSP.IO_Namespace]] obsolete.
 
* Mark all pages in [[Category:KSP.IO_Namespace]] obsolete.
 +
* Add the Namespace:blah template to API pages.
  
 
== API classes updated to KSP 1.04 ==
 
== API classes updated to KSP 1.04 ==
Line 16: Line 17:
  
 
== How to fix API templates ==
 
== How to fix API templates ==
 +
 +
'''I am in the process of <s>breaking</s> fixing the API templates. API tables may look wrong for the next day or two.''' [[User:Glyph|Glyph]] ([[User talk:Glyph|talk]]) 23:07, 16 October 2015 (UTC)
  
 
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>>.
 
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>>.
Line 21: Line 24:
 
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).
 
   
 
   
// 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
+
  |desc=string|default blank
// Used at the top of class pages.
+
 
Template:Class
+
  // Used at the top of class pages.
|name=string
+
  [[Template:Class]]
|summary=string|default blank
+
  |name=string
+
  |summary=string|default blank
// Template for a list of enumerations that are part of a class.
+
 
Template:ClassEnums
+
  // Template for a list of enumerations that are part of a class.
|enums=Template:ClassEnum...  <- List of Template:ClassEnum, without commas.
+
  [[Template:Enums]]
+
  |enums=Template:Enum...  <- List of Template:Enum, without commas.
// A section on a class page for enums belonging to that class.
+
 
Template:ClassEnum
+
  // A section on a class page for enums belonging to that class.
|name=string
+
  [[Template:Enum]]
|values=Template:ClassEnumValue...  <- List of Template:ClassEnumValue, without commas.
+
  |name=string
+
  |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.
+
 
Template:ClassEnumValue
+
  // A single enum value as part of Template:Enum. This is for enums on a class page, not enums on their own page.
|name=string
+
  [[Template:EnumValue]]
|value=string|default blank  <- If this enum value is given an actual int value, specify that value here (without the =).
+
  |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.
+
  |desc=string|default blank
Template:Properties
+
 
|properties=Template:Property...  <- List of Template:Property, without comma.
+
  // The Properties section of a class page.
+
  [[Template:Properties]]
// A single property in a Template:Properties section of a class page.
+
  |properties=Template:Property...  <- List of Template:Property, without comma.
Template:Property
+
 
|name=string
+
  // A single property in a Template:Properties section of a class page.
|type=Template:Type
+
  [[Template:Property]]
|access=string  <- "public" or "protected"
+
  |name=string
|get=true|default blank
+
  |type=Template:Type
|set=true|default blank
+
  |hasget=true|default blank
|static=true|default blank
+
  |hasset=true|default blank
|summary=string|default blank
+
  |access=string|default blank <- "public" or "protected"
+
  |static=true|default blank
// The Fields section of a class page.
+
  |desc=string|default blank
Template:Fields
+
 
|fields=Template:Field...  <- List of Template:Field templates, no comma between them.
+
  // The Fields section of a class page.
+
  [[Template:Fields]]
// A single field in a Template:Fields section of a class page.
+
  |fields=Template:Field...  <- List of Template:Field templates, no comma between them.
Template:Field
+
 
|name=string
+
  // A single field in a Template:Fields section of a class page.
|type=Template:Type
+
  [[Template:Field]]
|access=string  <- "public" or "protected"
+
  |name=string
|static=true|default blank
+
  |type=Template:Type
|const=true|default blank
+
  |access=string  <- "public" or "protected"
|initialValue=string|default blank
+
  |static=true|default blank
|summary=string|default blank
+
  |const=true|default blank
+
  |initialValue=string|default blank
// The Methods section of a class page.
+
  |summary=string|default blank
Template:Methods
+
 
|methods=Template:Method...  <- List of Template:Method templates, no comma between them.
+
  // The Methods section of a class page.
+
  [[Template:Methods]]
// A single method in a Template:Methods section of a class page.
+
  |methods=Template:Method...  <- List of Template:Method templates, no comma between them.
Template:Method
+
 
|name=string
+
  // A single method in a Template:Methods section of a class page.
|returnType=Template:Type|blank  <- blank for constructor
+
  [[Template:Method]]
|access=string  <- "public" or "protected"
+
  |name=string
|static=true|default blank
+
  |returnType=Template:Type|blank  <- blank for constructor
|virtual=true|default blank
+
  |access=string  <- "public" or "protected"
|args=Template:Arg, ...  <- Comma separated list of Template:Arg. Actually separated by ", " (comma and a space).
+
  |static=true|default blank
|summary=string|default blank
+
  |virtual=true|default blank
+
  |args=Template:Arg, ...  <- Comma separated list of Template:Arg. Actually separated by ", " (comma and a space).
// A single method argument.
+
  |summary=string|default blank
Template:Arg
+
 
|name=string
+
  // A single method argument.
|type=Template:Type
+
  [[Template:Arg]]
|defaultValue=string|default blank  <- The default value for this argument, i.e. this is an optional argument.
+
  |name=string
|ref=ref|out|default blank  <- If this argument is a "ref" or "out" argument, or blank for neither.
+
  |type=Template:Type
+
  |defaultValue=string|default blank  <- The default value for this argument, i.e. this is an optional argument.
// A type (class) and its generics, if any.
+
  |ref=ref|out|default blank  <- If this argument is a "ref" or "out" argument, or blank for neither.
Template:Type
+
 
|name=string  <- The actual identifier for the type. List<Dictionary<Blah, Blah>> has the name List.
+
  // A type (class) and its generics, if any.
                  This, and nothing else, is linked to other pages via API:{name}.
+
  [[Template:Type]]
|array=true|default blank  <- If set true, end type with [].
+
  |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}.
|generic=Template:Generic|default blank  <- If blank, this type is simple. If not, this type uses a
+
  |array=true|default blank  <- If set true, end type with [].
                                            generics template e.g. List<int> would have Template:Generic(Template:Type(int)).
+
  |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.
+
  // 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.

Latest revision as of 00:53, 17 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

I am in the process of breaking fixing the API templates. API tables may look wrong for the next day or two. Glyph (talk) 23:07, 16 October 2015 (UTC)

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
 |desc=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 =).
 |desc=string|default blank
 // 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
 |hasget=true|default blank
 |hasset=true|default blank
 |access=string|default blank  <- "public" or "protected"
 |static=true|default blank
 |desc=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.