New Wiki UnitDef Tag Documentation

[FLOZi]

http://springrts.com/wiki/Units-UnitDefs

Feedback desired before I go ahead and make entries for all the tags.

Is it readable? Is there any vital information missing? etc.

[SanadaUjiosan]

Looks pretty good to me. I skimmed through most of it.

If I had to say something, I'd say that I personally find information like that easier to read and look through when its in a table, like this page: http://springrts.com/wiki/Units:FBI, but this works too.

I see at the bottom there is an Examples section. I think that should be nice and strong, examples is the easiest way to learn in my opinion.

[FLOZi]

I considered tables but
1. I find them really ugly,
2. I figured this will mostly be used as a 'ctrl-f wtf does this damn tag do anyway?' resource rather than anyone reading through the whole thing.

If there is consensus that it would be preferable I will reconsider though.

Btw if anyone is thinking min/max values like this page I don't think its useful to fill the page with the largest value a 32bit float can hold. Instead, if a tag has a particular minimum value, it is mentioned in the description.

[knorke]

nice.
also the grouping into groups like Movement/Transports etc is good.
Later, some categories could probally get their own detailed page that explains what tags you need to combine to get ie a working transport.
(kind of like http://springrts.com/wiki/Unit_collision_volumes for hitboxes)

I was thinking what happens when things change (ie default values) and if maybe those comments would be easier to just have in the engine code (there already are some) but I am not sure devs would want that.
So lets just hope that the wiki will always be updated

Btw, forum could do with a wiki section maybe?
Wiki has talk pages but nobody seems to use/read them.

[FLOZi]

I was thinking what happens when things change (ie default values) and if maybe those comments would be easier to just have in the engine code (there already are some) but I am not sure devs would want that.

Hoijui is in favour of this; personally, I am not.

If comments are in UnitDef.cpp then it will get really ugly. Less so if they are in UnitDef.h but then they are in a separate place to the default values. Furthermore noobs are afraid of engine source as it is, but people always go trawling through the wiki looking for answers (then get annoyed when they don't find them there).

Plus if it stays on the wiki, then, as you said, we can have the categories linking to pages describing how to combine the tags in detail. Not to mention that wiki gives us lots more power over presentation than simple C++ comments.

It just seems to me that, having it on the wiki is actually more integrated with other documentation -FOR GAME DEVS- than having it in the source.

And, generally speaking, in the age of lua, relatively few tags are added or defaults changed (Except kloot added 2 for me just today ). Keeping pace with the changes is easier than it was a few years ago when the pages I am hoping to replace (after all, most of this information is already on the wiki in one shape or another!) were written, especially as engine devs now put more focus on informing game devs of changes.

A place to discuss wiki would be good, I am open to a subforum here or reactivating wiki talk pages. We can setup a lobby channel if we need to talk real-time and #moddev and #lua aren't free, but I don't think that's too likely.

[hoijui]

(engine) devs would very much like documentation in the engine code. it would be a better solution, because:

• documenting something where it is defined is the most logic thing to do
• there is a very widely accepted/used way of documenting in available (doxygen)
• (engine) devs can benefit from the comments when browsing the code or deving (shown in IDEs)
• engine devs might improve/correct them
• modders can look at the docu on github or on doxygen output, or even an automatic wiki generator could be written (i see no need for it)
• documentation is correctly versioned
• no duplication of documentation
• no additional workload of keeping the wiki up-to-date
• devs new to engine coding would have an easier live (me too ) when trying to understand parts of the code

i think doxygen is well enough formatted for every possible mod dev.

categories are natively supported by doxygen. they can be added in the source file.

indeed, doc-comments should be in the .h, not .cpp.

default values would be duplicated. the actual programmatic value is present in the .cpp, and referenced/documented in the comment in .h.

[knorke]

If comments are in UnitDef.cpp then it will get really ugly. Less so if they are in UnitDef.h but then they are in a separate place to the default values.

Another problem is that in engine tags sometimes have different names then in unitDef files. ie health / maxDamage.

I always look in the .cpp because you can easily see everything there:
health = udTable.GetFloat("maxDamage", 0.0f);
While in the .h it just says:
float health;
If comments were in the .h, it would have to be like:
float health; //how many hitpoints a unit has. the unitDef name is "maxDamage", default is 0.
In the .cpp it would just be:
health = udTable.GetFloat("maxDamage", 0.0f); //how many hitpoints a unit has.

[FLOZi]

Which reminds me, I should maybe document when they are different, for the purpose of accessing them in lua.

[knorke]

oh and +1 for wiki subforum. There are often some global issues...ie why does the google search disappear when logged in?

[PicassoCT]

Found this very informativ and helpfull, thx Flozi

[SanadaUjiosan]

Furthermore noobs are afraid of engine source as it is, but people always go trawling through the wiki looking for answers (then get annoyed when they don't find them there).

I am a constant proponent of wiki documentation. I'll never look at the source just because it wouldn't do me any good. I know updating wiki's suck, but we need more know-how initiative like Flozi to keep this going!

[Google_Frog]

This looks good, I found out about the cloakTimeout tag just with a quick browse.

Which reminds me, I should maybe document when they are different, for the purpose of accessing them in lua.

Do you mean accessing them via the UnitDefs table? Documenting that on the same page would be very messy as there is not a 1-1 correspondence between the unit defs and the UnitDefs table. The table has extra entries calculated from the tags and it is impossible to read some unit tags with the UnitDefs table.

[hoijui]

just wanted to point out that as it stands, no single argument pro documenting directly in the wiki remains. the only rational reasons why everyone would still argument pro doing it that way, is that they either didn't get it, or that they fear you FLOZi, would not do the work anymore if they expressed otherwise.

[knorke]

Even if it gets added as comments into engine it would not be lost work because the descriptions could be copy & pasted.
And well, that did not happen for 6 years so how likely is it to happen now?

[sunspot]

Even if it gets added as comments into engine it would not be lost work because the descriptions could be copy & pasted.
And well, that did not happen for 6 years so how likely is it to happen now?

Fact of the matter is hardly any developer in the world likes to write documentation because the their code is just so transparent, that it it's code documented ... Hardly rings true in any project I've been in though.

In our company we use wiki as well to document basic actions. How to build a screen from scratch in our framework for examle. Pitfalls we have to look out for etc... I for one find flozi's work VERY VERY educational and helped me A LOT during my mod development. So wether it is still needed to document on the wiki or not because it's in the code is not an issue. Flozi's goal was to educate newcommers as me to what things mean ... AND he succeeded so mission accomplished imho

[PicassoCT]

i know we all would luv to have brilliant updated wikis, and ever now and then a gem comes along, in which the truth is strong- like this one, or knorkes tutorial wiki. But those moments are rare, and not to be found while the halftruth wikis are around.

I m still for simply taking moddevs channelhistory every day, pumping it as one endless scroll to search into the wiki, and be done with it, by having a search that rates by date&searchwords. It is not a nice solution, but its the one which is the most realistic.

[FLOZi]

just wanted to point out that as it stands, no single argument pro documenting directly in the wiki remains.

Can doxygen do all the cross referencing and stuff in the wiki article? I still feel that code comments should be a guide to engine devs and wiki to content devs - imo there is a substantial gap between the information which should be presented to each group.

they fear you FLOZi

*powertrip*

[hoijui]

this feeling of you. can you somehow put it into words?

i understand there is info that might not be interesting for engine devs, but is so for mod devs (for example, if the tag in Lua is different then the member var in C++), but that does not mean that it would hurt any engine dev if this info would be in the code. actually the code is still the perfect spot for that info, because that mapping is done in engine code. if it changes, it changes in one commit, and the docu should change in the same commit. the wiki, if static, would always be wrong for either the current dev or the released version of spring, while the docu in the code (and generated one) could be correct for both.

in the doc (doxygen), you can have http links to wiki pages or link to other tags in the same or an other C++ file. what kind of links are you referring to exactly?

and yeah.. power brings fear!
they even WANT to fear you!

[Forboding Angel]

Flozi, I love you.

[sunspot]

this feeling of you. can you somehow put it into words?

i understand there is info that might not be interesting for engine devs, but is so for mod devs (for example, if the tag in Lua is different then the member var in C++), but that does not mean that it would hurt any engine dev if this info would be in the code. actually the code is still the perfect spot for that info, because that mapping is done in engine code. if it changes, it changes in one commit, and the docu should change in the same commit. the wiki, if static, would always be wrong for either the current dev or the released version of spring, while the docu in the code (and generated one) could be correct for both.

in the doc (doxygen), you can have http links to wiki pages or link to other tags in the same or an other C++ file. what kind of links are you referring to exactly?

and yeah.. power brings fear!
they even WANT to fear you!

I suppose doxygen is a bit like javadoc ? Annotations above the classes that get generated in some kind of documentation file ? If this exist, where can I find the output ?