Documentation rules

[frankystone]

I've started to make a wikiarticle about documentation rules: https://www.widelands.org/wiki/Documentation%20Rules/

Since i want to work on the documentation i have a question about string constants like e.g. for roadtypes: Currently they are formatted like ‘normal’, ‘busy’, or ‘waterway’. Since they are strings we should use another formatting imho. Something like "normal", "busy", or "waterway" ?

What do you think?

[Noordfrees]

+1 for surrounding them with "quotes", otherwise some scripters might think these are global constants

[Noordfrees]

Since the API is intended to be backward-compatible for future versions it would be good to add a note in which version a feature was introduced for all functions added after v1.0.
Is there some standard way to add a :since_version: tag or something like this to a method/attribute description? Or does this need to go in the description text?

[frankystone]

According to the doc you can use:

.. versionadded:: version
   text

.. versionchanged:: version
   text

.. deprecated:: version
   text

Not tested.

[Noordfrees]

Thanks :)

Looks good:

[frankystone]

whohoo... is there someone working on different types of ships? 👍

Don't forget real life. It's somewhere out of here :)