Merge pull request #546 from starkda/master

added documentation to matrix.xml.
cqfn · Mar 14, 2024 · aa9b976 · aa9b976
2 parents 89fdad1 + d590266
commit aa9b976
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 15 deletions.
diff --git a/src/main/java/org/jpeek/App.java b/src/main/java/org/jpeek/App.java
@@ -137,7 +137,6 @@ public App(final Path source, final Path target,
      * Analyze sources.
 
      * @throws IOException If fails
-     * @todo #452:30min Extract report building
      *  Analyze method is too big. We need to extract report building from
      *  here and use a map instead of if statements se we can make
      *  easier to add and remove metrics from execution.

diff --git a/src/main/resources/org/jpeek/xsd/matrix.xsd b/src/main/resources/org/jpeek/xsd/matrix.xsd
@@ -22,11 +22,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 -->
-<!--
-@todo #134:30min Matrix.xsd: add `xsd:documentation` tags as per issue #134. We need to
- document the schemas in src/resources/org/jpeek/xsd so that the semantics of
- the generated XML documents is transparent for maintainers.
--->
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="matrix">
     <xs:complexType>
@@ -37,26 +32,81 @@ SOFTWARE.
               <xs:element name="class" minOccurs="0" maxOccurs="unbounded">
                 <xs:complexType>
                   <xs:sequence>
+                    <xs:annotation>
+                      <xs:documentation>
+                        Matrix of metrics for each class. Rows are classes and columns are cohesion metrics
+                        (CAMC, LCOM5, MMAC, NHD, SCOM)
+                      </xs:documentation>
+                    </xs:annotation>
                     <xs:element name="metric" minOccurs="1" maxOccurs="unbounded">
                       <xs:complexType>
-                        <xs:attribute name="name" use="required" type="xs:string"/>
-                        <xs:attribute name="color" use="required" type="xs:string"/>
-                        <xs:attribute name="rank" use="required" type="xs:float"/>
+                        <xs:attribute name="name" use="required" type="xs:string">
+                          <xs:annotation>
+                            <xs:documentation>
+                              Metric name
+                            </xs:documentation>
+                          </xs:annotation>
+                        </xs:attribute>
+                        <xs:attribute name="color" use="required" type="xs:string">
+                          <xs:annotation>
+                            <xs:documentation>
+                              Represents rank for each metric. Order is green, yellow, red.
+                            </xs:documentation>
+                          </xs:annotation>
+                        </xs:attribute>
+                        <xs:attribute name="rank" use="required" type="xs:float">
+                          <xs:annotation>
+                            <xs:documentation>
+                              Rank of a metric. Used to find out the color.
+                            </xs:documentation>
+                          </xs:annotation>
+                        </xs:attribute>
                       </xs:complexType>
                     </xs:element>
                   </xs:sequence>
-                  <xs:attribute name="id" use="required" type="xs:string"/>
-                  <xs:attribute name="short_id" use="required" type="xs:string"/>
-                  <xs:attribute name="rank" use="required" type="xs:float"/>
-                  <xs:attribute name="trust" use="required" type="xs:float"/>
+                  <xs:attribute name="id" use="required" type="xs:string">
+                    <xs:annotation>
+                      <xs:documentation>The fully qualified java class name.</xs:documentation>
+                    </xs:annotation>
+                  </xs:attribute>
+                  <xs:attribute name="short_id" use="required" type="xs:string">
+                    <xs:annotation>
+                      <xs:documentation>
+                        The shorten java class name, where each dot separated package is shortened
+                        to it's first letter.
+                      </xs:documentation>
+                    </xs:annotation>
+                  </xs:attribute>
+                  <xs:attribute name="rank" use="required" type="xs:float">
+                    <xs:annotation>
+                      <xs:documentation>
+                        An average value of all metrics rank, scaled down into range [0,1].
+                      </xs:documentation>
+                    </xs:annotation>
+                  </xs:attribute>
+                  <xs:attribute name="trust" use="required" type="xs:float">
+                    <xs:annotation>
+                      <xs:documentation>
+                        The reciprocal of amount of different colors of metrics.
+                      </xs:documentation>
+                    </xs:annotation>
+                  </xs:attribute>
                 </xs:complexType>
               </xs:element>
             </xs:sequence>
           </xs:complexType>
         </xs:element>
       </xs:all>
-      <xs:attribute name="date" use="required" type="xs:dateTime"/>
-      <xs:attribute name="version" use="required" type="xs:string"/>
+      <xs:attribute name="date" use="required" type="xs:dateTime">
+        <xs:annotation>
+          <xs:documentation>Date when the skeleton was generated.</xs:documentation>
+        </xs:annotation>
+      </xs:attribute>
+      <xs:attribute name="version" use="required" type="xs:string">
+        <xs:annotation>
+          <xs:documentation>Version of jpeek when the skeleton was generated.</xs:documentation>
+        </xs:annotation>
+      </xs:attribute>
     </xs:complexType>
   </xs:element>
 </xs:schema>