Merge pull request #3448 from yo-h/java-qldoc-add

Java: improve QLDoc completeness

Author: aschackmull

java/ql/src/Advisory/Documentation/JavadocCommon.qll

@@ -1,3 +1,5 @@
+/** Provides classes and predicates related to Javadoc conventions. */
+
 import java
 
 /** Holds if the given `Javadoc` contains a minimum of a few characters of text. */
@@ -29,6 +31,7 @@ class DocuRefType extends RefType {
     this.isPublic()
   }
 
+  /** Holds if the Javadoc for this type contains a minimum of a few characters of text. */
   predicate hasAcceptableDocText() { acceptableDocText(this.getDoc().getJavadoc()) }
 }
 
@@ -46,8 +49,10 @@ class DocuCallable extends Callable {
     not this.getLocation() = this.getDeclaringType().getLocation()
   }
 
+  /** Holds if the Javadoc for this callable contains a minimum of a few characters of text. */
   predicate hasAcceptableDocText() { acceptableDocText(this.getDoc().getJavadoc()) }
 
+  /** Gets a string to identify whether this callable is a "method" or a "constructor". */
   string toMethodOrConstructorString() {
     this instanceof Method and result = "method"
     or

java/ql/src/Advisory/Naming/NamingConventionsCommon.qll

@@ -1,5 +1,8 @@
+/** Provides classes and predicates related to Java naming conventions. */
+
 import java
 
+/** A field that is both `static` and `final`. */
 class ConstantField extends Field {
   ConstantField() {
     this.isStatic() and

java/ql/src/Architecture/Dependencies/UnusedMavenDependencies.qll

@@ -1,3 +1,5 @@
+/** Provides classes and predicates for working with Maven dependencies. */
+
 import java
 import semmle.code.xml.MavenPom
 

java/ql/src/Compatibility/JDK9/JdkInternals.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides predicates for identifying unsupported JDK-internal APIs.
+ */
+
 /**
  * Provides a QL encoding of the list of unsupported JDK-internal APIs at:
  *

java/ql/src/Compatibility/JDK9/JdkInternalsReplacement.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides predicates for identifying suggested replacements for unsupported JDK-internal APIs.
+ */
+
 /**
  * Provides a QL encoding of the suggested replacements for unsupported JDK-internal APIs listed at:
  *

java/ql/src/default.qll

@@ -1 +1,3 @@
+/** DEPRECATED: use `java.qll` instead. */
+
 import java

java/ql/src/external/Clover.qll

@@ -1,3 +1,5 @@
+/** Provides classes and predicates for working with Clover reports. */
+
 import java
 
 /**
@@ -18,6 +20,7 @@ class CloverCoverage extends XMLElement {
     this.getName() = "coverage"
   }
 
+  /** Gets a project for this `coverage` element. */
   CloverProject getAProject() { result = this.getAChild() }
 }
 
@@ -27,6 +30,7 @@ class CloverCoverage extends XMLElement {
  * all subclasses of this class, to share code.
  */
 abstract class CloverMetricsContainer extends XMLElement {
+  /** Gets the Clover `metrics` child element for this element. */
   CloverMetrics getMetrics() { result = this.getAChild() }
 }
 
@@ -44,42 +48,61 @@ class CloverMetrics extends XMLElement {
 
   private float ratio(string name) { result = attr("covered" + name) / attr(name).(float) }
 
+  /** Gets the value of the `conditionals` attribute. */
   int getNumConditionals() { result = attr("conditionals") }
 
+  /** Gets the value of the `coveredconditionals` attribute. */
   int getNumCoveredConditionals() { result = attr("coveredconditionals") }
 
+  /** Gets the value of the `statements` attribute. */
   int getNumStatements() { result = attr("statements") }
 
+  /** Gets the value of the `coveredstatements` attribute. */
   int getNumCoveredStatements() { result = attr("coveredstatements") }
 
+  /** Gets the value of the `elements` attribute. */
   int getNumElements() { result = attr("elements") }
 
+  /** Gets the value of the `coveredelements` attribute. */
   int getNumCoveredElements() { result = attr("coveredelements") }
 
+  /** Gets the value of the `methods` attribute. */
   int getNumMethods() { result = attr("methods") }
 
+  /** Gets the value of the `coveredmethods` attribute. */
   int getNumCoveredMethods() { result = attr("coveredmethods") }
 
+  /** Gets the value of the `loc` attribute. */
   int getNumLoC() { result = attr("loc") }
 
+  /** Gets the value of the `ncloc` attribute. */
   int getNumNonCommentedLoC() { result = attr("ncloc") }
 
+  /** Gets the value of the `packages` attribute. */
   int getNumPackages() { result = attr("packages") }
 
+  /** Gets the value of the `files` attribute. */
   int getNumFiles() { result = attr("files") }
 
+  /** Gets the value of the `classes` attribute. */
   int getNumClasses() { result = attr("classes") }
 
+  /** Gets the value of the `complexity` attribute. */
   int getCloverComplexity() { result = attr("complexity") }
 
+  /** Gets the ratio of the `coveredconditionals` attribute over the `conditionals` attribute. */
   float getConditionalCoverage() { result = ratio("conditionals") }
 
+  /** Gets the ratio of the `coveredstatements` attribute over the `statements` attribute. */
   float getStatementCoverage() { result = ratio("statements") }
 
+  /** Gets the ratio of the `coveredelements` attribute over the `elements` attribute. */
   float getElementCoverage() { result = ratio("elements") }
 
+  /** Gets the ratio of the `coveredmethods` attribute over the `methods` attribute. */
   float getMethodCoverage() { result = ratio("methods") }
 
+  /** Gets the ratio of the `ncloc` attribute over the `loc` attribute. */
   float getNonCommentedLoCRatio() { result = attr("ncloc") / attr("loc") }
 }
 
@@ -100,6 +123,7 @@ class CloverPackage extends CloverMetricsContainer {
     this.getName() = "package"
   }
 
+  /** Gets the Java package for this Clover package. */
   Package getRealPackage() { result.hasName(getAttribute("name").getValue()) }
 }
 
@@ -122,8 +146,10 @@ class CloverClass extends CloverMetricsContainer {
     this.getName() = "class"
   }
 
+  /** Gets the Clover package for this Clover class. */
   CloverPackage getPackage() { result = getParent().(CloverFile).getParent() }
 
+  /** Gets the Java type for this Clover class. */
   RefType getRealClass() {
     result
         .hasQualifiedName(getPackage().getAttribute("name").getValue(),

java/ql/src/semmle/code/java/frameworks/JavaxAnnotations.qll

@@ -1,31 +1,50 @@
+/**
+ * Provides classes and predicates for working with annotations in the `javax` package.
+ */
+
 import java
 
 /*
- * javax.annotation annotations
+ * Annotations in the package `javax.annotation`.
  */
 
+/**
+ * A `@javax.annotation.Generated` annotation.
+ */
 class GeneratedAnnotation extends Annotation {
   GeneratedAnnotation() { this.getType().hasQualifiedName("javax.annotation", "Generated") }
 }
 
+/**
+ * A `@javax.annotation.PostConstruct` annotation.
+ */
 class PostConstructAnnotation extends Annotation {
   PostConstructAnnotation() { this.getType().hasQualifiedName("javax.annotation", "PostConstruct") }
 }
 
+/**
+ * A `@javax.annotation.PreDestroy` annotation.
+ */
 class PreDestroyAnnotation extends Annotation {
   PreDestroyAnnotation() { this.getType().hasQualifiedName("javax.annotation", "PreDestroy") }
 }
 
+/**
+ * A `@javax.annotation.Resource` annotation.
+ */
 class ResourceAnnotation extends Annotation {
   ResourceAnnotation() { this.getType().hasQualifiedName("javax.annotation", "Resource") }
 }
 
+/**
+ * A `@javax.annotation.Resources` annotation.
+ */
 class ResourcesAnnotation extends Annotation {
   ResourcesAnnotation() { this.getType().hasQualifiedName("javax.annotation", "Resources") }
 }
 
 /**
- * A javax.annotation.ManagedBean annotation.
+ * A `@javax.annotation.ManagedBean` annotation.
  */
 class JavaxManagedBeanAnnotation extends Annotation {
   JavaxManagedBeanAnnotation() {
@@ -34,71 +53,104 @@ class JavaxManagedBeanAnnotation extends Annotation {
 }
 
 /*
- * javax.annotation.security annotations
+ * Annotations in the package `javax.annotation.security`.
  */
 
+/**
+ * A `@javax.annotation.security.DeclareRoles` annotation.
+ */
 class DeclareRolesAnnotation extends Annotation {
   DeclareRolesAnnotation() {
     this.getType().hasQualifiedName("javax.annotation.security", "DeclareRoles")
   }
 }
 
+/**
+ * A `@javax.annotation.security.DenyAll` annotation.
+ */
 class DenyAllAnnotation extends Annotation {
   DenyAllAnnotation() { this.getType().hasQualifiedName("javax.annotation.security", "DenyAll") }
 }
 
+/**
+ * A `@javax.annotation.security.PermitAll` annotation.
+ */
 class PermitAllAnnotation extends Annotation {
   PermitAllAnnotation() {
     this.getType().hasQualifiedName("javax.annotation.security", "PermitAll")
   }
 }
 
+/**
+ * A `@javax.annotation.security.RolesAllowed` annotation.
+ */
 class RolesAllowedAnnotation extends Annotation {
   RolesAllowedAnnotation() {
     this.getType().hasQualifiedName("javax.annotation.security", "RolesAllowed")
   }
 }
 
+/**
+ * A `@javax.annotation.security.RunAs` annotation.
+ */
 class RunAsAnnotation extends Annotation {
   RunAsAnnotation() { this.getType().hasQualifiedName("javax.annotation.security", "RunAs") }
 }
 
 /*
- * javax.interceptor annotations
+ * Annotations in the package `javax.interceptor`.
  */
 
+/**
+ * A `@javax.interceptor.AroundInvoke` annotation.
+ */
 class AroundInvokeAnnotation extends Annotation {
   AroundInvokeAnnotation() { this.getType().hasQualifiedName("javax.interceptor", "AroundInvoke") }
 }
 
+/**
+ * A `@javax.interceptor.ExcludeClassInterceptors` annotation.
+ */
 class ExcludeClassInterceptorsAnnotation extends Annotation {
   ExcludeClassInterceptorsAnnotation() {
     this.getType().hasQualifiedName("javax.interceptor", "ExcludeClassInterceptors")
   }
 }
 
+/**
+ * A `@javax.interceptor.ExcludeDefaultInterceptors` annotation.
+ */
 class ExcludeDefaultInterceptorsAnnotation extends Annotation {
   ExcludeDefaultInterceptorsAnnotation() {
     this.getType().hasQualifiedName("javax.interceptor", "ExcludeDefaultInterceptors")
   }
 }
 
+/**
+ * A `@javax.interceptor.Interceptors` annotation.
+ */
 class InterceptorsAnnotation extends Annotation {
   InterceptorsAnnotation() { this.getType().hasQualifiedName("javax.interceptor", "Interceptors") }
 }
 
 /*
- * javax.jws annotations
+ * Annotations in the package `javax.jws`.
  */
 
+/**
+ * A `@javax.jws.WebService` annotation.
+ */
 class WebServiceAnnotation extends Annotation {
   WebServiceAnnotation() { this.getType().hasQualifiedName("javax.jws", "WebService") }
 }
 
 /*
- * javax.xml.ws annotations
+ * Annotations in the package `javax.xml.ws`.
  */
 
+/**
+ * A `@javax.xml.ws.WebServiceRef` annotation.
+ */
 class WebServiceRefAnnotation extends Annotation {
   WebServiceRefAnnotation() { this.getType().hasQualifiedName("javax.xml.ws", "WebServiceRef") }
 }

java/ql/src/semmle/code/java/frameworks/gwt/GWT.qll

@@ -1,3 +1,5 @@
+/** Provides classes and predicates for working with the GWT framework. */
+
 import java
 import GwtXml
 import GwtUiBinder

java/ql/src/semmle/code/java/frameworks/gwt/GwtUiBinder.qll

@@ -8,26 +8,44 @@
 import java
 import GwtUiBinderXml
 
+/**
+ * An annotation in the package `com.google.gwt.uibinder.client`.
+ */
 class GwtUiBinderClientAnnotation extends Annotation {
   GwtUiBinderClientAnnotation() { getType().getPackage().hasName("com.google.gwt.uibinder.client") }
 }
 
+/**
+ * A `@com.google.gwt.uibinder.client.UiHandler` annotation.
+ */
 class GwtUiHandlerAnnotation extends GwtUiBinderClientAnnotation {
   GwtUiHandlerAnnotation() { getType().hasName("UiHandler") }
 }
 
+/**
+ * A `@com.google.gwt.uibinder.client.UiField` annotation.
+ */
 class GwtUiFieldAnnotation extends GwtUiBinderClientAnnotation {
   GwtUiFieldAnnotation() { getType().hasName("UiField") }
 }
 
+/**
+ * A `@com.google.gwt.uibinder.client.UiTemplate` annotation.
+ */
 class GwtUiTemplateAnnotation extends GwtUiBinderClientAnnotation {
   GwtUiTemplateAnnotation() { getType().hasName("UiTemplate") }
 }
 
+/**
+ * A `@com.google.gwt.uibinder.client.UiFactory` annotation.
+ */
 class GwtUiFactoryAnnotation extends GwtUiBinderClientAnnotation {
   GwtUiFactoryAnnotation() { getType().hasName("UiFactory") }
 }
 
+/**
+ * A `@com.google.gwt.uibinder.client.UiConstructor` annotation.
+ */
 class GwtUiConstructorAnnotation extends GwtUiBinderClientAnnotation {
   GwtUiConstructorAnnotation() { getType().hasName("UiConstructor") }
 }