![[de]](/mwf/flags/de.png "Germany")
When looking at the System.ocg recently, it occured to me that we already have some documentation for our global script functions that could be made more visible if it were put into the documentation. So I wrote a small change to the script parser in the engine and made it put out xml files like this one:<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE funcs SYSTEM '../../../clonk.dtd'>
<?xml-stylesheet type='text/xsl' href='../../../clonk.xsl'?>
<funcs>
<func>
<title>Concatenate</title>
<syntax>
<rtype>any</rtype>
<params>
<param>
<type>array</type>
<name>first</name>
</param>
<param>
<type>array</type>
<name>second</name>
</param>
</params>
</syntax>
<desc> concatenates two arrays and returns a new array</desc>
<remark>planet/System.ocg/Array.c</remark>
</func>
</funcs>I think I can make the engine deduce the rtype in a lot of cases, and we could add a convention to document the parameters (func foo(int bar /* always 42 */) {} perhaps). Then I'd add a parameter to the engine or the c4script standalone to enable this so that I can put this code into the repository, and we could run that every once in a while. Do you think that we could get the quality of the comments in the source to a point where this would be useful enough?
>Do you think that we could get the quality of the comments in the source to a point where this would be useful enough?
Mh, a barrier for me to use that stuff while coding is that with most documentation systems you have to add a lot to describe a function
/*
// * CreateWobble
// *
// * This functions creates a new and all fresh wobble.
// *
// * parameter 1: int size: this parameter specifies the size of the wobble
// * parameter 2: int x: this parameter is the x coordinate of the wobble
// * parameter 3: int y: this parameter is the y coordinate of the wobble
// * parameter 4: int owner: the owner of the wobble
// * return value: asd
// *
*/
instead of
// this function creates a wobble, default owner NO_OWNER
func CreateWobble(int size, int x, int y, int owner);
or
// this function creates a wobble
func CreateWobble(int size, int x, int y, int owner /* default: NO_OWNER */);
if you want.
(And at least in this example I think the middle one is the easiest to understand when you are scanning through the code itself.)
And I am much likelier to write comments of the second kind. Especially because I think that my parameter names should be self-explanatory in most cases.
TL;DR: If you keep your documentation effort to a minimum, I will try to strongly adhere to it. If not, I cannot promise anything :x
![[ie]](/mwf/flags/ie.png "Ireland")
This kind of commenting rule would obviously only apply for scripts which are meant to be used by various objects (/developers) like System.ocg and Objects.ocd/Libraries.ocd. If I understand you correctly, your basic point is that you don't want to document your own code? Even assuming that you most probably don't need a lecture on usefulness of documentation.
>your basic point is that you don't want to document your own code?
My point is that I don't want to invest more time into typing the documentation than it would actually help someone who tries to understand my code.
Compare my first example with the dozens of // * with my second example.
I would say that my second example is easier to understand for someone who scans through the code - even though the first one is obviously a stricter and probably better to parse documentation style (and reminds me of java docs) :)
> even though the first one is obviously a stricter and probably better to parse documentation style
And that's probably what we want to achieve? You're making it very easy for you here. But I take a real example if you wish so: MeleeWeapons.ocd
That's 410 lines of code and to be honest not everytime self-explanatory. It took me a hard time understanding parts of it and if I wanted to make a new melee weapon for my AwesomeWeaponsPack.ocd a lot of what you dismiss as "scanning through the code" is to be done.
I take another 'easy' example: ApplyWeaponBash(pTo, int strength, angle) - I have no idea what this does even though the function is a oneliner; adding an effect. I will have to 'scan through' all your FxIntIsBeingStruck* functions in order to understand it. Because there is not a single comment next to it. I ain't even sure if I'm allowed to call it in my weapon or if its an internal something for your lib.
My point is not that I have documented my stuff enough in the past (that's obviously not the case). My point is that, let's say I had documented ApplyWeaponBash with a decent descriptions of what it does.How much would you need the line "parameter object pTo object to apply the bash to"? or "parameter int strength: strength of the bash applied"
> How much would you need the line "parameter object pTo object to apply the bash to"?
As much as it's needed in 'the real docu'. It doesn't hurt you much and when it's done, it's done and as Newton stated, many editors with proper syntax highlighting will colour doc-comments (/** */) differently.
>/*
>// * CreateWobble
>// *
>// * This functions creates a new and all fresh wobble.
>// *
>// * parameter 1: int size: this parameter specifies the size of the wobble
>// * parameter 2: int x: this parameter is the x coordinate of the wobble
>// * parameter 3: int y: this parameter is the y coordinate of the wobble
>// * parameter 4: int owner: the owner of the wobble
>// * return value: asd
>// *
>*/
>func CreateWobble(int size, int x, int y, int owner);
What? You are exaggerating. Another example:
/**
* Deals weapon damage to an object. Calls <code>OnWeaponBash</code>
* in the target object which can nullify the damage dealt.
*
* @param target target object
* @param strength strength in which to strike in energy to subtract
* @param angle optional. Angle to strike from.
*
* @return whether the damage has been dealt successfully.
*/
func ApplyWeaponBash(object target, int strength, int angle);Also, note that proper editors/IDEs show and highlight doc-comments properly and differently from other comments (color) so that they don't obstruct the reading of the source file. Additionally, C4DT generates the context help from javadoc-comments for its autocomplete/in-context-documentation feature which makes coding much more convenient.
Well, I am used to typing with the keyboard - and even when I used a macro to create a template for such a documentation block, I would have to switch to the mouse to click behind every @param and enter my text there.I am not saying that it's impossible to provide a good documentation with such a template. I am just saying that from my experience the motivation to do so is much, much lower.
In your example
* @param target target object: "Well, yes, I would have thought so"PS: I'd much rather have a usable documentation that is used nearly everywhere than a perfect documentation that is used nearly nowhere
I'm a fan of "do not repeat yourself" (which in this case forbids repeating the names of the parameters in a comment) and not particularly inclined to write a comment contents parser, so my proposal looks like this:// Frobnicates the target until it dies or the timeout expires.
global func Frobnicate(
object target,
int timeout /* maximum duration in frames */
)
{
/*
var victim = CreateObject(Clonk);
Frobnicate(victim, 10);
*/
[...]
}
Powered by mwForum 2.29.7 © 1999-2015 Markus Wichitill
