1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
* Documentation of build rules, expressions, etc
Build rules can obtain a non-trivial complexity. This is especially
true if several rules have to exist for slightly different use
cases, or if the rule supports many different fields. Therefore,
documentation of the rules (and also expressions for the benefit
of rule authors) is desirable.
Experience shows that documentation that is not versioned together with
the code it refers to quickly gets out of date, or lost. Therefore,
we add documentation directly into the respective definitions.
** Multi-line strings in JSON
In JSON, the newline character is encoded specially and not taken
literally; also, there is not implict joining of string literals.
So, in order to also have documentation readable in the JSON
representation itself, instead of single strings, we take arrays
of strings, with the understanding that they describe the strings
obtained by joining the entries with newline characters.
** Documentation is optional
While documentation is highly recommended, it still remains optional.
Therefore, when in the following we state that a key is for a list
or a map, it is always implied that it may be absent; in this case,
the empy array or the empty map is taken as default, respectively.
** Rules
Each rule is described as a JSON object with a fixed set of keys.
So having fixed keys for documentation does not cause conflicts.
More precisely, the keys ~doc~, ~field doc~, and ~config_doc~
are reserved for documentation. Here, ~doc~ has to be a list of
strings describing the rule in general. ~field doc~ has to be a map
from (some of) the field names to an array of strings, containing
additional information on that particular field. ~config_doc~ has
to be a map from (some of) the config variables to an array of
strings describing the respective variable.
*** Example
#+BEGIN_SRC
{ "library":
{ "doc":
[ "A C library"
, ""
, "Define a library that can be used to be statically linked to a"
, "binary. To do so, the target can simply be specified in the deps"
, "field of a binary; it can also be a dependecy of another library"
, "and the information is then propagated to the corresponding binary."
]
, "string_fields": ["name"]
, "target_fields": ["srcs", "hdrs", "private-hdrs", "deps"]
, "field_doc":
{ "name":
["The base name of the libary (i.e., the name without the leading lib)."]
, "srcs": ["The source files (i.e., *.c files) of the library."]
, "hdrs":
[ "The public header files of this library. Targets depending on"
, "this library will have access to those header files"
]
, "private-hdrs":
[ "Additional internal header files that are used when compiling"
, "the source files. Targets depending on this library have no access"
, "to those header files."
]
, "deps":
[ "Any other libraries that this library uses. The dependency is"
, "also propagated (via the link-deps provider) to any consumers of"
, "this target. So only direct dependencies should be declared."
]
}
, "config_vars": ["CC"]
, "config_doc":
{ "CC":
[ "single string. defaulting to \"cc\", specifying the compiler"
, "to be used. The compiler is also used to launch the preprocessor."
]
}
, "expression": { ... }
}
}
#+END_SRC
** Expressions
Expressions are also described by a JSON object with a fixed set of
keys. Here we use the keys ~doc~ and ~vars_doc~ for documentation,
where ~doc~ is an array of strings describing the expression as a
whole and ~vars_doc~ is a map from (some of) the ~vars~ to an array
of strings describing this variable.
** Export targets
As export targets play the role of interfaces between repositories,
it is important that they be documented as well. Again, export targets
are described as a JSON object with fixed set of keys amd we use
the keys ~doc~ and ~config_doc~ for documentation. Here ~doc~ is an
array of strings describing the targted in general and ~config_doc~
is a map from (some of) the variables of the ~flexible_config~ to
an array of strings describing this parameter.
** Presentation of the documentation
As all documentation are just values (that need not be evaluated)
in JSON objects, it is easy to write tool rendering documentation
pages for rules, etc, and we expect those tools to be written
independently. Nevertheless, for the benefit of developers using
rules from a git-tree roots that might not be checked out, there is
a subcommand ~describe~ which takes a target specification like the
~analyze~ command, looks up the corresponding rule and describes
it fully, i.e., prints in human-readable form
- the documentation for the rule
- all the fields available for that rule together with
- their type (~string_field~, ~target_field~, etc), and
- their documentation.
|
