Merge pull request #438 from felicity-semmle/cpp/SD-2777-delete-poor-qhelp

geoffw0 · web-flow · commit 77ca0cf9cb03 · 2018-11-14T14:21:24.000Z
C++: Delete qhelp files with little useful content (SD-2777)
diff --git a/cpp/ql/src/Architecture/General Class-Level Information/ClassHierarchies.qhelp b/cpp/ql/src/Architecture/General Class-Level Information/ClassHierarchies.qhelp
diff --git a/cpp/ql/src/Architecture/General Class-Level Information/ClassHierarchies.ql b/cpp/ql/src/Architecture/General Class-Level Information/ClassHierarchies.ql
@@ -1,6 +1,6 @@
 /**
  * @name Class hierarchies
- * @description Shows classes and their base classes.
+ * @description Shows an inheritance hierarchy for classes and their base classes.
  * @kind graph
  * @id cpp/architecture/class-hierarchies
  * @graph.layout organic
diff --git a/cpp/ql/src/Architecture/General Class-Level Information/HubClasses.qhelp b/cpp/ql/src/Architecture/General Class-Level Information/HubClasses.qhelp
diff --git a/cpp/ql/src/Architecture/General Class-Level Information/HubClasses.ql b/cpp/ql/src/Architecture/General Class-Level Information/HubClasses.ql
@@ -1,6 +1,6 @@
 /**
  * @name Hub classes
- * @description Shows coupling between classes; red, large boxes are hub types that depend on many other classes
+ * @description Shows coupling between classes. Large, red, boxes are hub types that depend on many other classes
  *              and are depended on by many other classes.
  * @kind treemap
  * @id cpp/architecture/hub-classes
diff --git a/cpp/ql/src/Architecture/General Class-Level Information/InheritanceDepthDistribution.qhelp b/cpp/ql/src/Architecture/General Class-Level Information/InheritanceDepthDistribution.qhelp
@@ -5,44 +5,30 @@
 
 
 <overview>
-<p>This query shows the distribution of inheritance depth across all types, i.e. classes. Library types are ignored.</p>
+<p>This query shows the distribution of inheritance depth across all types, that is, classes. Library types are ignored.</p>
 
 <p>The result of this query is a line graph showing, for each number <i>n</i>, how many types have an inheritance depth of <i>n</i>, where
 the inheritance depth of a type is the length of a longest path in the inheritance hierarchy from top class to the type.</p>
-
-<p>When hovering the mouse pointer over a specific depth value, the number of types having this inheritance depth is displayed.</p>
-
 </overview>
-<section title="How to Address the Query Results">
+
+<recommendation>
 <p>The depth of a type is an indication of how deeply nested a type is in a given design. 
 Very deep types can be an indication of over-engineering, whereas a system with predominantly shallow types 
 may not be exploiting object-orientation to the full.</p>
+</recommendation>
 
-
-
-
-
-</section>
 <references>
 <li>
-Shyam R. Chidamber and Chris F. Kemerer.
-<a href="http://www.pitt.edu/~ckemerer/CK%20research%20papers/MetricForOOD_ChidamberKemerer94.pdf">A Metrics Suite for Object Oriented Design
-</a>.
+Shyam R. Chidamber and Chris F. Kemerer,
+<i><a href="http://www.pitt.edu/~ckemerer/CK%20research%20papers/MetricForOOD_ChidamberKemerer94.pdf">A Metrics Suite for Object Oriented Design
+</a></i>.
 IEEE Transactions on Software Engineering,
-20(6), pages 476-493, June 1994.
-
+20(6), pages 476-493, June 1994.</li>
 
-
-<a href="http://www.dmst.aueb.gr/dds/index.en.html">Diomides D. Spinnelis</a>.
-<a href="http://www.spinellis.gr/codequality/">Code Quality: The Open Source Perspective</a>.
-Addison-Wesley 2007.
-
-
-
-<a href="http://www.dmst.aueb.gr/dds/index.en.html">Diomides D. Spinnelis</a>.
-<a href="http://www.spinellis.gr/sw/ckjm/">ckjm - Chidamber and Kemerer Java Metrics</a>.
-(implementation of CK metrics), 2006.
-
-
-
-</li></references></qhelp>
+<li>
+Lutz Prechelt, Barbara Unger, Michael Philippsen, and Walter Tich, <i><a href="http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.159.2229&amp;rep=rep1&amp;type=pdf">A Controlled Experiment on Inheritance Depth as a Cost Factor for Code Maintenance
+</a></i>.
+Journal of Systems and Software, 65 (2):115-126, 2003.
+</li>
+</references>
+</qhelp>
diff --git a/cpp/ql/src/Architecture/General Class-Level Information/InheritanceDepthDistribution.ql b/cpp/ql/src/Architecture/General Class-Level Information/InheritanceDepthDistribution.ql
@@ -1,6 +1,6 @@
 /**
  * @name Inheritance depth distribution
- * @description Shows distribution of inheritance depth across all classes.
+ * @description Shows the distribution of inheritance depth across all classes.
  * @kind chart
  * @id cpp/architecture/inheritance-depth-distribution
  * @chart.type line
diff --git a/cpp/ql/src/Architecture/General Namespace-Level Information/CyclicNamespaces.qhelp b/cpp/ql/src/Architecture/General Namespace-Level Information/CyclicNamespaces.qhelp
@@ -7,19 +7,15 @@
 <overview>
 <p>This query shows namespaces that cyclically depend 
 on one another.</p>
-
-<p />
-
 </overview>
-<section title="How to Address the Query Results">
-<p>If there are cyclic dependencies between packages, they cannot be developed and tested independently. It is thus preferable to
-eliminate such cycles from the program.</p>
-
-
-
 
+<recommendation>
+<p>If there are cyclic dependencies between packages, they cannot be developed and tested independently. 
+It is better to eliminate such cycles from the program.</p>
+</recommendation>
 
-</section>
 <references>
 <li>Robert Martin's <a href="https://drive.google.com/file/d/0BwhCYaYDn8EgOGM2ZGFhNmYtNmE4ZS00OGY5LWFkZTYtMjE0ZGNjODQ0MjEx/view">Acyclic Dependencies Principle</a>.
-</li></references></qhelp>
+</li>
+</references>
+</qhelp>
diff --git a/cpp/ql/src/Architecture/General Namespace-Level Information/GlobalNamespaceClasses.qhelp b/cpp/ql/src/Architecture/General Namespace-Level Information/GlobalNamespaceClasses.qhelp
@@ -5,18 +5,15 @@
 
 
 <overview>
-<p>This query finds classes that belong to no namespace</p>
-
+<p>This query finds classes that belong to no namespace.</p>
 </overview>
-<section title="How to Address the Query Results">
-<p>If there are too many classes that belong to no namespace, consider creating namespaces to get a better project structure.</p>
-
-
 
+<recommendation>
+<p>If there are many classes that belong to no namespace, consider defining namespaces to create a better project structure.</p>
+</recommendation>
 
-
-</section>
 <references>
-
+<li>C++ reference: <a href="https://en.cppreference.com/w/cpp/language/namespace">Namespaces</a>
+ </li>
 </references>
 </qhelp>
diff --git a/cpp/ql/src/Architecture/General Namespace-Level Information/GlobalNamespaceClasses.ql b/cpp/ql/src/Architecture/General Namespace-Level Information/GlobalNamespaceClasses.ql
@@ -1,6 +1,6 @@
 /**
  * @name Global namespace classes
- * @description Finds classes that belong to no namespace
+ * @description Finds classes that belong to no namespace.
  * @kind table
  * @id cpp/architecture/global-namespace-classes
  */
diff --git a/cpp/ql/src/Architecture/General Namespace-Level Information/NamespaceDependencies.qhelp b/cpp/ql/src/Architecture/General Namespace-Level Information/NamespaceDependencies.qhelp
diff --git a/cpp/ql/src/Architecture/General Namespace-Level Information/NamespaceDependencies.ql b/cpp/ql/src/Architecture/General Namespace-Level Information/NamespaceDependencies.ql
@@ -1,6 +1,6 @@
 /**
  * @name Namespace dependencies
- * @description Shows dependencies between namespaces.
+ * @description Shows dependencies between namespaces as a hierarchical graph.
  * @kind graph
  * @id cpp/architecture/namespace-dependencies
  * @graph.layout hierarchical
diff --git a/cpp/ql/src/Best Practices/RuleOfThree.qhelp b/cpp/ql/src/Best Practices/RuleOfThree.qhelp
@@ -8,17 +8,13 @@
 <p>This query finds classes that define a destructor, a copy constructor, or a copy assignment operator, but not all three of them. The compiler generates default implementations for these functions, and since they deal with similar concerns it is likely that if the default implementation of one of them is not satisfactory, then neither are those of the others.</p>
 
 <p>The query flags any such class with a warning, and also display the list of generated warnings in the result view.</p>
-
 </overview>
-<section title="How to Address the Query Results">
-<p>Explicitly define the missing functions.</p>
-
-
-
 
+<recommendation>
+<p>Explicitly define the missing functions.</p>
+</recommendation>
 
-</section>
 <references>
-<li><a href="http://en.wikipedia.org/wiki/Rule_of_three_(C%2B%2B_programming)">Wikipedia article</a>
-
-</li></references></qhelp>
+<li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Rule_of_three_(C%2B%2B_programming)">Rule of three (C++ programming)</a></li>
+</references>
+</qhelp>
diff --git a/cpp/ql/src/Metrics/Namespaces/AbstractNamespaces.qhelp b/cpp/ql/src/Metrics/Namespaces/AbstractNamespaces.qhelp
@@ -9,21 +9,17 @@
 
 <p>Abstractness measures the proportion of abstract types in
       a package relative to the total number of types in that package.
-      A highly abstract package (where the metric value is close 1)
-      that is furthermore instable is likely to be useless: the
-      class hierarchy has been over-engineered, and all those
-      abstract types are not heavily used.</p>
-
+      A metric value close to 1 indicates a highly abstract package
+      that is also unstable. The class hierarchy is probably over-engineered, and the abstract types are unlikely to be much used.</p>
 </overview>
-<section title="How to Address the Query Results">
-<p>Try to simplify the class hierarchy.</p>
-
-
 
+<recommendation>
+<p>Consider reducing the level of abstraction by simplifying the class hierarchy.</p>
+</recommendation>
 
-
-</section>
 <references>
-
+<li>C++ reference: <a href="https://en.cppreference.com/w/cpp/language/namespace">Namespaces</a>
+ </li>
+ <li>Geeks for Geeks: <a href="https://www.geeksforgeeks.org/abstraction-in-c/">Abstraction in C++</a></li>
 </references>
 </qhelp>
diff --git a/cpp/ql/src/Metrics/Namespaces/ConcreteNamespaces.qhelp b/cpp/ql/src/Metrics/Namespaces/ConcreteNamespaces.qhelp
@@ -5,18 +5,12 @@
 
 
 <overview>
-<p>This query finds namespaces that have an abstractness equal to 0. These namesspaces do not contain any abstract classes.</p>
-
+<p>This query finds namespaces that have an abstractness equal to 0. These namespaces do not contain any abstract classes.</p>
 </overview>
-<section title="How to Address the Query Results">
-<p />
-
-
 
-
-
-</section>
 <references>
-
+<li>C++ reference: <a href="https://en.cppreference.com/w/cpp/language/namespace">Namespaces</a>
+ </li>
+<li>Geeks for Geeks: <a href="https://www.geeksforgeeks.org/abstraction-in-c/">Abstraction in C++</a></li>
 </references>
 </qhelp>
diff --git a/cpp/ql/src/Metrics/Namespaces/HighAfferentCouplingNamespaces.qhelp b/cpp/ql/src/Metrics/Namespaces/HighAfferentCouplingNamespaces.qhelp
@@ -9,17 +9,10 @@
 
 <p>The query counts number of namespaces depending on a namespace and 
 displays those that have more than 20 namespaces depending on them.</p>
-
 </overview>
-<section title="How to Address the Query Results">
-<p />
-
-
 
-
-
-</section>
 <references>
-
+<li>C++ reference: <a href="https://en.cppreference.com/w/cpp/language/namespace">Namespaces</a>
+ </li>
 </references>
 </qhelp>
diff --git a/cpp/ql/src/Metrics/Namespaces/HighDistanceFromMainLineNamespaces.qhelp b/cpp/ql/src/Metrics/Namespaces/HighDistanceFromMainLineNamespaces.qhelp
@@ -5,25 +5,28 @@
 
 
 <overview>
-<p>This query finds namespaces that do not have a good balance between abstractness and stability.</p>
-
-<p>This measure intends to capture the trade-off between abstractness
-      and instability: the ideal situation occurs when the sum of
-      abstractness and instability is one. That is, a package is
+<p>This query finds namespaces that do not have a good balance between abstractness and stability where:</p>
+<ul>
+<li> 
+Abstractness measures the proportion of abstract types in a namespace relative to the total number of types in that namespace.
+</li>
+<li>
+Instability measures the level of expectation that changes to other namespaces will affect this namespace.
+</li>
+</ul>
+
+<p>The metric tries to capture the trade-off between abstractness
+      and instability. For an ideal balance, the sum of
+      abstractness and instability should be one. That is, a package is
       completely abstract and stable (abstractness=1 and instability=0)
       or it is concrete and instable (abstractness=0 and instability=1).
-      We thus measure the distance from that ideal situation.</p>
-
+      This query measures the distance between the balance in the code base
+      and the ideal.</p>
 </overview>
-<section title="How to Address the Query Results">
-<p />
-
-
 
-
-
-</section>
 <references>
-
+<li>C++ reference: <a href="https://en.cppreference.com/w/cpp/language/namespace">Namespaces</a>
+ </li>
+ <li>Geeks for Geeks: <a href="https://www.geeksforgeeks.org/abstraction-in-c/">Abstraction in C++</a></li>
 </references>
 </qhelp>
diff --git a/cpp/ql/src/Metrics/Namespaces/HighEfferentCouplingNamespaces.qhelp b/cpp/ql/src/Metrics/Namespaces/HighEfferentCouplingNamespaces.qhelp
diff --git a/cpp/ql/src/Metrics/Namespaces/StableNamespaces.qhelp b/cpp/ql/src/Metrics/Namespaces/StableNamespaces.qhelp
diff --git a/cpp/ql/src/Metrics/Namespaces/UnstableNamespaces.qhelp b/cpp/ql/src/Metrics/Namespaces/UnstableNamespaces.qhelp
