Not logged inOpenClonk Forum
Up Topic General / General / Documentation overhaul
- - By Newton [de] Date 2011-06-27 15:49
Hey guys. Now that the docs are updated automatically every night it became much more rewarding to work on the reference, rewarding enough that I also want to make my hands dirty. I already started to remove some obsolete documentation.

In here, I would like to gather all the big and small tasks that need to be done on the docs, both so I (and everyone else) gets a good overview what has to be done and also because I hope that others of the dev team and of the community will join into this little project and tick off the one or the other task.

I'll start the list with a few tasks that I stumbled over:
Parent - - By Newton [de] Date 2011-06-27 16:19 Edited 2011-07-31 23:19
Replace navigation bar with breadcrumb
Size: Small
Difficulty: Medium (involves coding in xml, probably python)
The navigation bar is not displayed correctly (always in German) and is by the way only a replica of what is in the contents index anyway. What would make much more sense from the usage point of view is to have a breadcrumb which reflects the same structure as seen in the contents index. The search link in the navigation bar is obsolete since we have the search field in the header. However, an additional search link could be integrated into the contents index.


Fix language switcher
Size: Tiny
Difficulty: Easy
The language switcher always shows the british flag, regardless of which language is currently selected. With additional translations of the documentation in the future in mind, the language switcher should appear in the upper right corner as a series of flags, the currently selected one highlighted.


Overhaul "game content" documentation
Size: Big
Difficulty: Easy
The documentation of the game content (object definitions, scenarios,...) is currently and was always not very comprehensible. An overhaul of these pages should:
+ include examples of the basic definition of an object/scenario. For example show a directory listing of an example scenario with a Music.ocg, System.ocg, local object definitions etc.
+ separate between the normal/basic/required files in an object/scenario and advanced stuff that may be included (Info.txt, Material.ocg, Sound.ocg...); give a guideline how a scenario/object pack etc. should be structured (in examples). F.e. stuff sound effects in their object definition or into Sound.ocg if they are scenario global sounds etc.
+ especially for object definitions with their graphics.pngs, meshes and skeletons, a grouping of the contents and their relations to each other is necessary, with examples


Reset the version numbers
Size: Medium
Difficulty: Easy
Reset the version numbers of all functions to OC 1.0. Reason: Clonk Rage has it's own documentation, we don't need to document for CR and earlier. Also, the signature of all functions have been changed anyway (namingly, the for_object parameter has been removed).
Parent - - By Günther [de] Date 2011-06-29 19:39
Here's the current state of my approach to the table-of-contents-on-every-page feature.

> Reset the version numbers


Having the old version numbers float around doesn't any harm as far as I can tell, so I think effort is better spent elsewhere :-)
Attachment: docs-Show-table-of-contents-on-every-page.patch - First version with <table> (3k)
Attachment: docs-Show-table-of-contents-on-every-page-v2.patch - Second version with position:absolute instead of <table> (4k)
Reply
Parent - By Newton [de] Date 2011-06-30 11:39
Yeah, it doesn't really have a high priority but if I do something, I do it completely. But since you mention it: Please do post the stuff about the documentation you think that should be overhauled slash changed here.
Parent - By Newton [de] Date 2011-06-27 16:24 Edited 2011-07-31 00:46
Fix the localization of code examples
Size: Big
Difficulty: Easy (requires knowledge of German)
For some reason, the comments and also the function names in code examples are not localized - meaning they are all in German. The function names should always be in English, the comments should be localized.

Fix code examples
Size: Big
Difficulty: Medium (requires knowledge of C4Script)
Many code examples don't work anymore. Let it be that the ID "ROCK" doesn't exist anymore or that something like GetX(GetCursor()) is used. All examples should be looked at and corrected.
Parent - By Newton [de] Date 2011-06-29 15:13
Fix whole documentation captions not being displayed in English
Size: Tiny
Difficulty: Easy
Parent - By Newton [de] Date 2011-06-30 12:38 Edited 2011-07-01 09:27
Add xml-property no-brackets
Size: Tiny
Difficulty: Easy
Certain "functions" in the documentation are not written with brackets. For example OCF, VIS and other constants but also stuff like this, return, etc. There should be a possibility to define in the xml that those are written without the brackets by the xsl in the documentation.
Parent - By Newton [de] Date 2011-07-01 09:34
Overhaul examples
Size: Big
Difficulty: Easy
The examples in many functions are not very helpful, not very creative. Many are something among these lines:
"FindObject(Find_ID(Clonk))->DoCon(100);
Makes a Clonk bigger by 100."
Overhauled examples should show a proper use case - they can be inspired or taken from an actual use in Objects.ocd or scenarios (Example), (additionally) edge cases can be shown in examples.  And don't forget, we can actually include images(!) in the documentation. Since clonk is a game (engine), it might make sense to not only describe the effect a function has, but also show it.
Parent - By Günther [de] Date 2011-07-01 13:44
http://docs.openclonk.org/en/sdk/definition/properties.html has blank spots and needs examples. Or maybe we want a separate page for every property?
http://docs.openclonk.org/en/sdk/definition/procedures.html still talks about physicals (should talk about ActMap properties instead)
http://docs.openclonk.org/en/sdk/definition/defcore.html#SektionPhysical
Reply
Parent - - By Newton [de] Date 2011-07-17 17:46 Edited 2011-07-27 15:19
Document the other Find_* functions.
Parent - By Newton [de] Date 2011-07-24 22:54
Peter volunteered to do that... right? :-P
- - By Newton [de] Date 2011-06-30 12:36 Edited 2011-07-02 22:50
While rummaging through the documentation, the following functions sounded fishy to me... are they obsolete?

VIS_Local  (is there still Local(0)?)
VIS_* (they are constants... perhaps they should get an own page like every constant and the function documentation removed?)
Activate
SkyParKeep (instead: use nil?)
Parent - - By Sven2 [de] Date 2011-06-30 14:31
bool Activate(object controller) on DigDouble or by context menu is probably obsolete. But isn't void Activate(int player) still called from the rules/goals menu?
Parent - By Newton [de] Date 2011-06-30 14:42
But this would be a callback then, no function.
Parent - - By Caesar [de] Date 2011-07-01 08:40
VIS_Local is not defined anymore, Local(0) is not used anymore (We don't have enumerated locals anymore, do we?), it's the property Visibility now.
Parent - - By Newton [de] Date 2011-07-01 09:26

>it's the property Visibility now.


What is the property Visibility now? Do you mean instead of Set/GetVisibility() or instead of VIS_Local?
Parent - - By Caesar [de] Date 2011-07-01 13:15
Visibility is both, Local(0) and Set/GetVisibility().
Parent - - By Newton [de] Date 2011-07-01 14:18
How?
Parent - - By Caesar [de] Date 2011-07-02 13:20 Edited 2011-07-02 13:26
As I get it, Visibility may be an integer or an array. Either the value or the value of the first element of the array take over the function of storing the VIS_*-mask. The rest of the array elements starting with 1 for player 0 are bool values for visibility for each player which are used if VIS_Select is set.
Other constants are: VIS_OverlayOnly, VIS_Owner, VIS_Allies, VIS_Enemies, VIS_God and VIS_LayerToggle (last is checked for the object's layer).
Parent - - By Newton [de] Date 2011-07-02 13:23
Uh oh, looks like somehtign that should *really* be documented thoroughly or done a bit more straightforward.
Parent - - By Caesar [de] Date 2011-07-02 13:27
It is straightforward:

Visibility = VIS_God | VIS_Owner
Visibility = [VIS_Select, 1, 0, 0, 1] //Visible for player 0 and 3
Visibility = [VIS_Enemies] //more compatible if you don't want to write functions checking every time if you have an array or an integer.
Parent - By Newton [de] Date 2011-07-02 17:03
this

>Visibility = [VIS_Enemies] //more compatible if you don't want to write functions checking every time if you have an array or an integer.

Parent - - By Newton [de] Date 2011-07-02 21:51
What I mean to say is: This complex behaviour is exactly the reason why direct access to variables/properties is sometimes not a good idea and the reason why there are setters/getters. If the mechanic of this property is like this, it should only be accessed by CheckVisibility(player) and a function SetVisibility() which both already take into account this behaviour.

Since properties are public by design, my suggestion is to have two properties: Visibility and VisibilityByPlayer or similar. If Visibility=VIS_Select, the VisibilityByPlayer property is looked at by functions. Opinions?
Parent - By Isilkor Date 2011-07-03 00:46 Edited 2011-07-03 00:49

> If Visibility=VIS_Select, the VisibilityByPlayer property is looked at by functions.


I really don't see what this gains us over having both merged into a single property. If anything, the property could use proper getter/setter functions, as you already mentioned. Pretend it'd always have to be an array if you want to keep it easy for documentation purposes.
Reply
- - By Newton [de] Date 2011-07-02 22:49
Document new Visibilty behaviour
Size: Medium
Difficulty: Easy
The way how the visibility of an object is set has changed. The documentation needs to be updated to account for that. This includes removal of Set/GetVisibility, VIS_Local, add other VIS_* constants and the explanation of the behaviour of the property. Perhaps a refactor of the interface (see in above discussion). I suggest to document the property "Visibility" and include a list of all VIS constants and their explanations there.
Parent - - By Caesar [de] Date 2011-07-03 18:46
I already did that half the way. I'll finish it soon.
Parent - - By Newton [de] Date 2011-07-17 17:52
Status?
Parent - - By Caesar [de] Date 2011-07-17 21:02
Just came back from a trip...
Parent - - By Newton [de] Date 2011-07-17 22:40
Nice, where to?
Parent - By Caesar [de] Date 2011-07-18 09:58
Abifahrt Korfu / Senior trip to Corfu. 8 nights there and I managed to catch a cold at 40°C and more. Anyway, was epic.
- By Newton [de] Date 2011-07-20 20:39
Rewrite Control-reference
In http://docs.openclonk.org/en/sdk/definition/script.html , everything below the heading "Control Functions" is obsolete and should be rewritten, taking into account http://forum.openclonk.org/topic_show.pl?tid=337
- - By Newton [de] Date 2011-07-20 20:51 Edited 2011-07-31 21:00
List the gamecalls
Which gamecalls there are exactly has not been documented. I am sure there is more than Initialize, InitializePlayer, RemovePlayer and GameOver, isn't there? Here http://docs.openclonk.org/en/sdk/scenario/script.html
Parent - - By Armin [de] Date 2011-07-20 22:24
Are RelaunchPlayer and OnClonkDeath another category?
Parent - By PeterW [gb] Date 2011-07-20 22:32
Well, those are called from script (the Clonk).
Parent - - By Newton [de] Date 2011-07-31 21:47
Also document the GameCalls made by the clonk (or move to the engine if it makes sense) as well as the goals.
Parent - - By Maikel Date 2011-07-31 21:54
It might be best to move these callbacks from the clonk to a library, and then document libraries. It's rather odd to have C4Script documented in our engine documentation.
Parent - - By Newton [de] Date 2011-07-31 22:36
Yeah, the libraries should really be documented in one or the other way. Otherwise, there would also be no control documentation (Control*-Callbacks). The question is, how and where?
Parent - - By Maikel Date 2011-07-31 23:51
If we provide the libraries with the engine(not sure what that exactly means, at least it means moving it out Objects.ocd [Objects.ocd can "include" Libraries.ocd]) we can also put them in the documentation.
Parent - - By Newton [de] Date 2011-07-31 23:52
(Why?)
Parent - By Zapper [de] Date 2011-08-01 06:38
I think he means because some of the libraries behave more like general helper scripts (that we currently put outside of Objects.ocd in System.ocg!) and could be used without the other objects from Objects.ocd.
More like a "standard library" for Clonk-C4Script.

What I don't like about it is that every scenario would have to include the library folder too. So unless an object package can specify other included packages itself I am not really for that idea. We can still document everything. And if we want to, we can move it later
- By Newton [de] Date 2011-07-30 16:34 Edited 2011-07-31 18:13
Fix effect interface
The effects need to be migrated to use effect.variables (with proper names), the "reserved" parameter needs to be removed from an effect function. Also, perhaps the time parameter should be removed as it is available always through effect.Time.
- By Newton [de] Date 2011-07-30 21:56 Edited 2011-07-31 01:21
remove GetComponent/NeededMatString extra parameter?
-> PSF_GetCustomComponents
- - By Newton [de] Date 2011-07-30 23:23
remove Set/GetProperty
It is now obsolete, isn't it? (Because of someobj.Bla and someobj["bla"])
Parent - - By Zapper [de] Date 2011-07-30 23:36
Does someobj[Format(...)] work? If not, we still need SetProperty
Parent - By Isilkor Date 2011-08-01 20:09
should work, just like var f=3;somearray[f]=1; works
Reply
- - By Newton [de] Date 2011-07-31 23:51
Alright, I am more or less done with the big overhaul. The rest are small things which might be adjusted on the go by someone who notices it. The most important thing is that now the documentation is useable (as in: correct) and one doesn't stumble over one obsolete thing after the other.

Edit: Ah, one thing is missing! The title page! http://docs.openclonk.org/en/sdk/ ... well, this I will do still, but probably later
Parent - - By Maikel Date 2011-07-31 23:53
That's good, I already was used to having the engine code always around. Great job, wouldn't have done it myself.
Parent - - By Newton [de] Date 2011-08-01 00:11
Me too, actually. With the engine code around, one can know for sure - the documentation could always be outdated or incomplete. (f.e. the object callbacks list is already quite old).

It needs more than one person to keep the documentation reasonably updated that one can rely on the information in the documentation. But seeing that the morale of the other engine devs to document their new features has been relatively good in the past, I am expecting that we can maintain it in an updated status now that the documentation is about ~up to date again.
Especially from Günther I hope to see that he becomes more anxious to finish documenting all those big changes he made (f.e.).
Parent - By Isilkor Date 2011-08-01 20:11
I wish we could document functions next to their (C++) definition, and pull that out into the HTML docs in some way.
Reply
Up Topic General / General / Documentation overhaul

Powered by mwForum 2.29.7 © 1999-2015 Markus Wichitill