somebodyisnobody/lcdocs

LC developer documentation extracted from OpenClonk

lcdocs's Issues

Funktionen veraltet-status prüfen

Bei folgenden Funktionen ist unklar, ob sie veraltet sind:

• Call
• DefinitionCall
• GetPathLength
• ObjectCall
• Par

Bei einigen Funktionen könnte eventuell auch auf FuncCall verwiesen werden, das kann ich aber fachlich nicht bewerten.

• GameCall
• GameCallEx

Beschreibungsseite für asynchrone Funktionen erstellen

Mit den letzten Commits wurde das Attribut "isAsync" (xs:boolean) am Hauptelement als required eingeführt. Ist dieses auf true gesetzt, so erscheint im transformierten Dokument ein Warnhinweis, dass die Funktion asynchron ist. Es soll auf eine entsprechende Erklärseite verweisen werden. Diese existiert noch nicht und muss geschrieben werden. Hier soll darauf eingegangen werden

• warum man bei solchen Funktionen aufpassen muss,
• wie bei falscher Handhabung im Netzwerkspiel Desyncs entstehen und
• was genau man trotzdem mit den Funktionen im Netzwerkspiel machen darf, ohne dass es Desyncs gibt.

Anschließend muss das Dokument hier mit relativem Pfad von sdk/ aus eingesetzt werden bevor das issue dicht gemacht werden kann:

lcdocs/clonk.xsl

Line 141 in 6b7233e

<xsl:variable as="xs:string" name="path-to-async-page" select="'fillme.html'"/> <!-- TODO -->

Funktionen ohne Clonkversion

Es gibt noch folgende Clonkfunktionen ohne Versionsangabe.

• Find_Layer()
• GetObjectLayer()
• SetObjectLayer()

Dieser Zustand blockiert das Schema:

lcdocs/clonk.xsd

Lines 291 to 292 in 22bf2d4

	<!-- TODO: remove before merging -->
	<xs:pattern value="N/A"/>

XML Schema Definition Annotations

Das Schema ist sehr dürftig kommentiert. Manche Elemente haben gar keine Beschreibung. Bei jedem Element mit Textinhalt (Mixed/SimpleType) sollte eine Beschreibung stehen, was als Inhalt erwartet wird.

Dokumentation übersetzen

Viele neue Strings aus jetzt neu dokumentierten Funktionen und Schemata müssen in der PO-file übersetzt werden. Auch wenn es den Git Log kaputt macht ist es hier vielleicht besser ein Programm zurate zu ziehen.

Dieser Schritt muss möglichst am Schluss gemacht werden, wenn sich an der Dokumentation inhaltlich vor dem Merge nichts mehr ändert.

Verlinkte nichtexistente Funktionen oder andere Ressourcen

Folgende Funktionen sind in den XML-Dateien als <funcLink> verlinkt, es existiert jedoch keine Dokumentation - ergo XML-File- darüber.

"GreaterThan"
"LessThan"
"Var"
"SetVar"
"SetMaterialColor"
"SetMenuTextProgress"
"SetPlrValue"
"GetViewMode"
"SetSkyColor"
"SetSkyFade"
"Global"
"InsertMaterialAmount"
"Local"
"Div"
"Mul"

Gleiches Problem mit <emLink> Elementen:
Funcs.xml -> "sdk/for.xml"
SetContactDensity.xml -> "sdk/material\index.xml"
script.html
-> sdk/script/fn/Construction.xml
-> sdk/script/fn/OCF_HitSpeed1.xml
-> sdk/script/fn/OCF_HitSpeed2.xml
-> sdk/script/fn/OCF_HitSpeed3.xml

Dies blockt die korrekte Ausführung im XSLT-Prozess:

lcdocs/clonk.xsl

Lines 604 to 605 in 22bf2d4

	<!-- TODO set terminate=yes when running in production-->
	<xsl:message terminate="no">Can't find the function "<xsl:value-of select="normalize-space(.)"/>"</xsl:message>

Passende Kategorie für die Get*Val Funktionsgruppe

Die Get*Val Funktionsgruppe sollte in einer generischeren Kategorie als "Get*Val" eingeordnet sein. Als Benutzer der Dokumentation möchte ich auch mit wenig C4Scripterfahrung anhand der Kategorien meine benötigten Funktionen finden. Ein generischer Name muss also noch gefunden werden.

Der Zustand blockiert das Schema:

lcdocs/clonk.xsd

Lines 239 to 240 in 22bf2d4

	<!-- TODO rename @maxmitti -->
	<xs:enumeration value="Get*Val"/>

Buildscripte anpassen

Die Buildscripte müssen angepasst werden:

• Während das alte Kategoriesystem fest aus Ober- und Unterkategorie mit eigenen XML-Elementen bestand, ist das neue System bei Bedarf auch höher drei-, vier- oder fünfdimensional und wird aus einem XML-Element gelesen, wobei die Dimensionen durch ein "/" getrennt sind.
• Es wurden Konstantengruppen im Schema eingefügt. Diese müssen im Buildscript berücksichtigt und in der contents.html platziert werden
• Gleiches gilt für Funktionscallbacks

Generate Const-value via XSLT

I don't remember me if there was a reason for the value element in a <const>.

lcdocs/clonk.xsd

Lines 145 to 148 in 421c784

	<xs:element name="category" type="functionCategory"/>
	<xs:element name="description" type="htmlText"/>
	<xs:element name="version" type="clonkVersionOrUnknown"/>
	<xs:element name="value" type="xs:integer"/>

@maxmitti Is there a scenario where the value is not determinable via XSLT trough

• the bitfield if it's a custom bitmask or
• the order of the const elements?

Otherwise I would remove the value element and calculate it via XSLT.

Sort_* Funktionen vervollständigen

Die Sort_* Funktionen müssen vervollständigt werden. Also Version, Beispiele, Erläuterungen der Parameter. Ich habe das schon etwas angefangen, komme aber fachlich nicht weiter:

• Sort_Reverse
• Sort_Multiple
• Sort_Distance
• Sort_Random
• Sort_Speed
• Sort_Mass
• Sort_Value
• Sort_Func

C4D-Konstantengruppe vervollständigen

Es fehlen (wenn ich das richtig in Erinnerung habe) Konstanten, die in der C4D-Konstantengruppe dokumentiert werden müssen.