Difference between revisions of "User:Glyph"

From Kerbal Space Program Wiki
Jump to: navigation, search
(How to fix API templates)
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Things that need doing ==
+
== Things that need doing on the wiki ==
  
* PropertiesStart and PropertiesEnd templates to be replaced with Properties to fit in line with Methods, Fields, etc.
 
 
* 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.
 
* 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.
 
* 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.
 +
* Add the Namespace:blah template to API pages.
  
 
== API classes updated to KSP 1.04 ==
 
== API classes updated to KSP 1.04 ==
Line 17: Line 18:
 
== How to fix API templates ==
 
== 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. Using special generics tags is not enough.
+
'''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>>.
  
 
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.
 +
  [[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)).
  
Template:Class
+
  // A list of generic types, as part of a Template:Type.
|name=string
+
  [[Template:Generics]]
|summary=string|default blank
+
  |types=Template:Type,...  <- All the types that this generic template has, comma separated.
 
Template:Properties
 
|properties=Template:Property...  <- List of Template:Property templates, no comma between them.
 
 
Template:Property
 
|name=string
 
|type=Template:Type
 
|access=string  <- "public" or "protected"
 
|get=true|default blank
 
|set=true|default blank
 
|summary=string|default blank
 
 
Template:Fields
 
|fields=Template:Field...  <- List of Template:Field templates, no comma between them.
 
 
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
 
 
Template:Methods
 
|methods=Template:Method...  <- List of Template:Method templates, no comma between them.
 
 
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.
 
|summary=string|default blank
 
 
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.
 
 
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)).
 
 
Template:Generic
 
|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.