# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1696262857 -7200
# Node ID e55f318a8b8b49ce3509771922187c692df62edb
# Parent  ef0635b78b7b9996af8f6df4c45249ec15e1dc67
first version of an XML documentation - fixes #266

diff -r ef0635b78b7b -r e55f318a8b8b uwproj.xsd
--- a/uwproj.xsd	Mon Oct 02 16:55:40 2023 +0200
+++ b/uwproj.xsd	Mon Oct 02 18:07:37 2023 +0200
@@ -8,6 +8,14 @@
     <xs:element name="project" type="ProjectType"/>
 
     <xs:complexType name="ProjectType">
+        <xs:annotation>
+            <xs:documentation>
+                The root element of an uwproj project.
+                Consists of an optional <code>config</code> element
+                and an arbitrary number of <code>dependency</code>
+                and <code>target</code> elements.
+            </xs:documentation>
+        </xs:annotation>
         <xs:sequence>
             <xs:element name="config" type="ConfigType" minOccurs="0"/>
             <xs:element name="dependency" type="DependencyType" minOccurs="0" maxOccurs="unbounded"/>
@@ -16,12 +24,31 @@
     </xs:complexType>
 
     <xs:complexType name="ConfigType">
+        <xs:annotation>
+            <xs:documentation>
+                The configuration section.
+                Consists of an arbitrary number of <code>var</code> elements.
+            </xs:documentation>
+        </xs:annotation>
         <xs:sequence>
             <xs:element name="var" type="ConfigVarType" minOccurs="0" maxOccurs="unbounded"/>
         </xs:sequence>
     </xs:complexType>
 
     <xs:complexType name="ConfigVarType">
+        <xs:annotation>
+            <xs:documentation>
+                The definition of a configuration variable.
+                <p>
+                    Configuration variables are supposed to be used in the configure script and are also
+                    written to the resulting config file (in contrast to make variables, which are only
+                    written to the config file).
+                    The <code>name</code> attribute is mandatory, the value is defined by the text body of the element.
+                    The optional Boolean <code>exec</code> attribute (false by default) controls, whether the entire
+                    definition is automatically executed under command substitution.
+                </p>
+            </xs:documentation>
+        </xs:annotation>
         <xs:simpleContent>
             <xs:extension base="xs:string">
                 <xs:attribute name="name" type="xs:string" use="required"/>
@@ -31,6 +58,13 @@
     </xs:complexType>
 
     <xs:complexType name="PkgConfigType">
+        <xs:annotation>
+            <xs:documentation>
+                Instructs configure to invoke <code>pkg-config</code>, if present on the system, to determine
+                compiler and linker flags. The text body of this element defines the package name to search.
+                To constrain the allowed versions, use the attributes <code>atleast, exact, max</code>.
+            </xs:documentation>
+        </xs:annotation>
         <xs:simpleContent>
             <xs:extension base="xs:string">
                 <xs:attribute name="atleast" type="xs:string"/>
@@ -41,6 +75,12 @@
     </xs:complexType>
 
     <xs:simpleType name="LangType">
+        <xs:annotation>
+            <xs:documentation>
+                Requests a compiler for the specified language. Allowed values are
+                c, cpp.
+            </xs:documentation>
+        </xs:annotation>
         <xs:restriction base="xs:string">
             <xs:enumeration value="c"/>
             <xs:enumeration value="cpp"/>
@@ -48,14 +88,40 @@
     </xs:simpleType>
 
     <xs:complexType name="DependencyType">
+        <xs:annotation>
+            <xs:documentation>
+                Declares a dependency.
+                <p>
+                    If the optional <code>name</code> attribute is omitted, the dependency is global
+                    and must be satisfied, otherwise configuration shall fail.
+                    A <em>named dependency</em> can be referenced by a target (or is implicitly referenced
+                    by the default target, if no targets are specified).
+                    Multiple declarations for the same named dependency may exist, in which case each declaration
+                    is checked one after another, until one block is satisfied. The result of the first satisfied
+                    dependency declaration is supposed to be applied to the config file.
+                </p>
+                <p>
+                    The optional <code>platform</code> attribute may specify a <em>single</em> platform identifier and
+                    the optional <code>not</code> attribute may specify a comma-separated list of platform identifiers.
+                    The configure script shall skip this dependency declaration if the detected platform is not
+                    matching the filter specification of these attributes.
+                </p>
+            </xs:documentation>
+        </xs:annotation>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
             <xs:element name="lang" type="LangType"/>
             <xs:element name="cflags" type="FlagsType"/>
             <xs:element name="cxxflags" type="FlagsType"/>
             <xs:element name="ldflags" type="FlagsType"/>
             <xs:element name="pkgconfig" type="PkgConfigType"/>
-            <xs:element name="test" type="xs:string"/>
-            <xs:element name="make" type="xs:string"/>
+            <xs:element name="test" type="xs:string">
+                <xs:annotation>
+                    <xs:documentation>
+                        Specifies a custom command that shall be executed to test whether this dependency is satisfied.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="make" type="MakeVarType"/>
         </xs:choice>
         <xs:attribute name="name" type="xs:string"/>
         <xs:attribute name="platform" type="xs:string"/>
@@ -63,6 +129,13 @@
     </xs:complexType>
 
     <xs:complexType name="FlagsType">
+        <xs:annotation>
+            <xs:documentation>
+                Instructs configure to append the contents of the element's body to the respective flags variable.
+                If the optional <code>exec</code> flag is set to <code>true</code>, the contents are supposed to be
+                executed under command substitution <em>at configuration time</em> before they are applied.
+            </xs:documentation>
+        </xs:annotation>
         <xs:simpleContent>
             <xs:extension base="xs:string">
                 <xs:attribute name="exec" type="xs:boolean" default="false"/>
@@ -71,6 +144,25 @@
     </xs:complexType>
 
     <xs:complexType name="TargetType">
+        <xs:annotation>
+            <xs:documentation>
+                Declares a build target that is supposed to be configured.
+                <p>
+                    If no build target is declared explicitly, an implicit default
+                    target is generated, which has the <code>alldependencies</code>
+                    flag set.
+                </p>
+                <p>
+                    The optional <code>name</code> attribute is also used to generate a prefix
+                    for the compiler and linker flags variables.
+                    Furthermore, a target may consist of an arbitrary number of <code>feature</code>,
+                    <code>option</code>, and <code>define</code> elements.
+                    Named dependencies can be listed (separated by comma) in the <code>dependencies</code>
+                    element. If this target shall use <em>all</em> available named dependencies, the empty
+                    element <code>alldependencies</code> can be used as a shortcut.
+                </p>
+            </xs:documentation>
+        </xs:annotation>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
             <xs:element name="feature" type="FeatureType"/>
             <xs:element name="option" type="OptionType"/>
@@ -84,6 +176,18 @@
     </xs:complexType>
 
     <xs:complexType name="FeatureType">
+        <xs:annotation>
+            <xs:documentation>
+                Declares an optional feature, that can be enabled during configuration, if all
+                <code>dependencies</code> are satisfied.
+                If a feature is enabled, all <code>define</code> and <code>make</code> definitions are
+                supposed to be applied to the config file.
+                In case the optional <code>default</code> attribute is set to true, the feature is enabled by default
+                and is supposed to be automatically disabled (without error) when the dependencies are not satisfied.
+                The name that is supposed to be used for the --enable and --disable arguments can be optionally
+                specified with the <code>arg</code> attribute. Otherwise, the <code>name</code> is used by default.
+            </xs:documentation>
+        </xs:annotation>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
             <xs:group ref="TargetDataGroup"/>
         </xs:choice>
@@ -93,6 +197,17 @@
     </xs:complexType>
 
     <xs:complexType name="OptionType">
+        <xs:annotation>
+            <xs:documentation>
+                Declares a configuration option.
+                The option argument name is specified with the <code>arg</code> attribute.
+                Then, the children of this element specify possible <code>values</code> by defining the conditions
+                (in terms of dependencies) and effects (in terms of defines and make variables) of each value.
+                Finally, a set of <code>default</code>s is specified which supposed to automagically select the most
+                appropriate value for a specific platform under the available dependencies (in case the option is not
+                explicitly specified by using the command line argument).
+            </xs:documentation>
+        </xs:annotation>
         <xs:sequence>
             <xs:element name="value" type="OptionValueType" minOccurs="0" maxOccurs="unbounded"/>
             <xs:element name="default" type="OptionDefaultType" minOccurs="0" maxOccurs="unbounded"/>
@@ -101,6 +216,12 @@
     </xs:complexType>
 
     <xs:complexType name="OptionValueType">
+        <xs:annotation>
+            <xs:documentation>
+                Declares a possible value for the option (in the <code>str</code> attribute) and
+                the conditions (<code>dependencies</code>) and effects, the value has.
+            </xs:documentation>
+        </xs:annotation>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
             <xs:group ref="TargetDataGroup"/>
         </xs:choice>
@@ -108,6 +229,14 @@
     </xs:complexType>
 
     <xs:complexType name="OptionDefaultType">
+        <xs:annotation>
+            <xs:documentation>
+                Specifies a default value for this option. Multiple default values can be specified, in which case
+                they are checked one after another for availability. With the optional <code>platform</code> attribute,
+                the default value can be constrained to a <em>single</em> specific platform and is supposed to be
+                skipped by configure, when this platform is not detected.
+            </xs:documentation>
+        </xs:annotation>
         <xs:attribute name="value" type="xs:string" use="required"/>
         <xs:attribute name="platform" type="xs:string"/>
     </xs:complexType>
@@ -116,16 +245,37 @@
         <xs:choice>
             <xs:element name="define" type="DefineType" minOccurs="0" maxOccurs="unbounded"/>
             <xs:element name="dependencies" type="DependenciesType" minOccurs="0" maxOccurs="unbounded"/>
-            <xs:element name="make" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
+            <xs:element name="make" type="MakeVarType" minOccurs="0" maxOccurs="unbounded"/>
         </xs:choice>
     </xs:group>
 
     <xs:complexType name="DefineType">
+        <xs:annotation>
+            <xs:documentation>
+                Specifies C/C++ pre-processor definitions that are supposed to
+                be appended to the compiler flags, if supported.
+                (Note: for example, Fortran also supports C/C++ style pre-processor definitions under
+                certain circumstances)
+            </xs:documentation>
+        </xs:annotation>
         <xs:attribute name="name" type="xs:string" use="required"/>
         <xs:attribute name="value" type="xs:string"/>
     </xs:complexType>
 
     <xs:simpleType name="DependenciesType">
+        <xs:annotation>
+            <xs:documentation>A comma-separated list of named dependencies.</xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string"/>
+    </xs:simpleType>
+
+    <xs:simpleType name="MakeVarType">
+        <xs:annotation>
+            <xs:documentation>
+                The text contents in the body of this element are supposed to be appended literally
+                to the config file without prior processing.
+            </xs:documentation>
+        </xs:annotation>
         <xs:restriction base="xs:string"/>
     </xs:simpleType>
 </xs:schema>
\ No newline at end of file