documentation attempt at umgebung.h

[Dwachs]

here is a patch that introduces proper comment formatting to get nice output by doxygen. Any comments?

[kierongreen]

(not your fault but it's difficult to see exactly which bits have been changed due to diff structure!)

However from what I can work out the following are definite improvements:
Grouping related settings together in code
Standardising formatting of comments
Giving more explanation for certain variables (e.g. message_flags)

Is there a reason for removing the enum for station_coverage_show? If it is a boolean value (which searching through source is how it is used, aside from it's definition and reading as a byte) then it would be clearer as that, and using true/false.

[prissi]

This would certainly help. Is there a link on what doxygen need for comments? (The /// was new to me.)

Ok, I found also ///< for comments after a statement.

Since I have very limited experience with doxygen, what are the suggestions you would recomment for future use? I would happily comply with (even though ///< is ugly ... )

[Dwachs]

Is there a reason for removing the enum for station_coverage_show? If it is a boolean value (which searching through source is how it is used, aside from it's definition and reading as a byte) then it would be clearer as that, and using true/false.

The enum is never used, the corresponding variable is used as if it were a boolean. I did not change that, since it would require the change of load/save routines.

The variable quit_simutrans does not really fit into this class, it should be a member of karte_t.

As to doxygen: To get documentation of classes, member functions etc, the declarations or implementations of them must be preceded by comment blocks like

Code Select Expand


/**
* this is a large comment block
*/
class blub_t {...

or

Code Select Expand


/// this is a brief comment
uint8 bla


The triple /// is needed, // is interpreted as plain comment, and will not be used by doxygen. ///< can be used to document eg enum members.

In these blocks, extra markup like
-- @param to document parameters of functions
-- @returns to document return value
-- @see to include a "See also" block in the documentation with cross-links
should be used.

It is also possible to group things in a class / file like I did in the patch above. If I understand correctly, this creates 'local' groups: the documentation of eg class members is split into groups. There is also the possibility to create global groups to indicate that things belong to the same unit (like network stuff).

As far as I understand, doxygen understand references to classes, functions, files etc if inserted in the comment text like

Code Select Expand


/**
* this variable is used in ground_t when calling grund_t::hat_weg in grund.cc
*/


In this way it is possible to document the relation between code pieces. I do not know, whether this helps to understand the program-flow.

[prissi]

Please submit, I want to submit chnages to umgebung_t (new variable) ...

[Dwachs]

done.