1Content Definition Tags  {#content_tags}
2=======================
3
4Content entries may have tags associated with them to help filter them
5for later effects.
6
7Tags are used to easily filter for entries, without relying on the specific
8entries names.
9
10These filters are applied in various areas, such as:
11
12 * displaying only certain parts in the design window
13 * not showing buildings unless other criteria are met
14 * only affecting certain ships within a system.
15
16
17Documenting tags
18----------------
19
20To document content tags you can use the custom `@content_tag` Doxygen
21keyword:
22
23```
24\@content_tag{TAG_NAME} brief description
25```
26
27To document C++ defined tags use regular comments, however keep in
28mind, that each documentation need to be unique within the symbol
29scope to properly be registered Doxygen.
30
31```cpp
32// \@content_tag{TAG_ONE} Documentation for tag one
33int SomeFunction(std::string tag = "TAG_ONE");
34
35// \@content_tag{TAG_HARD_WORK} Documentation for tag hard work
36const std::string TAG_HARD_WORK = "TAG_HARD_WORK";
37
38// \@content_tag{TAG_LESS_WORK} Documentation for tag less work
39const std::string TAG_LESS_WORK = "TAG_LESS_WORK";
40
41void OneFunction(UniverseObject& obj) {
42    if (obj.HasTag(TAG_HARD_WORK))
43        DoHardWork(obj);
44    else if (obj.HasTag(TAG_LESS_WORK))
45        DoLessWork(obj);
46}
47
48void AnotherFunc(UniverseObject& obj) {
49    // This will be overwritten by TAG_BAD_OVERWRITE
50    // \@content_tag{TAG_BAD_LOST} Documentation will be overwritten
51    if (obj.HasTag("TAG_BAD_LOST"))
52        DoHardWork();
53    // \@content_tag{TAG_BAD_OVERWRITE} Documentation will occur twice
54    else if (obj.HasTag("TAG_BAD_OVERWRITE"))
55        DoLessWork();
56}
57```
58
59With Python, docstring comments do not support special commands, instead use the hash form #
60
61```py
62def AnotherFunc(some_object):
63    # \@content_tag{TAG_DO_WORK} Documentaion for "do work" tag
64    if universe.getObject(some_object).hasTag("TAG_DO_WORK"):
65        do_work
66```
67
68For FOCS use the special c style form of triple slashes ///
69
70```
71EffectsGroup
72    scope = And [
73        Ship
74        /// \@content_tag{CTRL_SAMPLE2} Sample 2
75        Not HasTag name = "CTRL_SAMPLE2"
76        WithinDistance distance = Source.Size condition = Source
77    ]
78    effects = ...
79```
80
81
82Content Definition Tag Listing
83------------------------------
84
85The following list of availble tags is auto generated, it may not be
86visible outside of Doxygen generated content.
87