Java: make some SMAP predicates private and add QLDoc

yo-h · yo-h · commit 9bb949a8b132 · 2020-11-26T13:55:19.000-05:00
diff --git a/java/ql/src/semmle/code/Location.qll b/java/ql/src/semmle/code/Location.qll
@@ -6,7 +6,7 @@
 
 import FileSystem
 import semmle.code.java.Element
-import semmle.code.SMAP
+private import semmle.code.SMAP
 
 /** Holds if element `e` has name `name`. */
 predicate hasName(Element e, string name) {
@@ -72,7 +72,7 @@ class Top extends @top {
     )
   }
 
-  predicate hasLocationInfoAux(
+  private predicate hasLocationInfoAux(
     string filepath, int startline, int startcolumn, int endline, int endcolumn
   ) {
     exists(File f, Location l | fixedHasLocation(this, l, f) |
diff --git a/java/ql/src/semmle/code/SMAP.qll b/java/ql/src/semmle/code/SMAP.qll
@@ -1,6 +1,14 @@
+/**
+ * Provides classes and predicates for working with SMAP files (see JSR-045).
+ */
+
 import java
 
-predicate smap(File inputFile, int inLine, File outputFile, int outLineStart, int outLineEnd) {
+/**
+ * Holds if there exists a mapping between an SMAP input file and line
+ * and a corresponding SMAP output file and line range.
+ */
+private predicate smap(File inputFile, int inLine, File outputFile, int outLineStart, int outLineEnd) {
   exists(
     string defaultStratum, int inputFileNum, int inStart, int inCount, int outStart, int outIncr,
     int n
@@ -15,13 +23,24 @@ predicate smap(File inputFile, int inLine, File outputFile, int outLineStart, in
   )
 }
 
-predicate smap(File inputFile, int inLine, File outputFile, int outLine) {
+/**
+ * Holds if there exists a mapping between an SMAP input file and line
+ * and a corresponding SMAP output file and line.
+ */
+private predicate smap(File inputFile, int inLine, File outputFile, int outLine) {
   exists(int outLineStart, int outLineEnd |
     smap(inputFile, inLine, outputFile, outLineStart, outLineEnd) and
     outLine in [outLineStart .. outLineEnd]
   )
 }
 
+/**
+ * Holds if an SMAP input location (with path, line and column information)
+ * has a corresponding SMAP output location (with path and line information).
+ *
+ * For example, an SMAP input location may be a location within a JSP file,
+ * which may have a corresponding SMAP output location in generated Java code.
+ */
 predicate hasSmapLocationInfo(
   string inputPath, int isl, int isc, int iel, int iec, string outputPath, int osl, int oel
 ) {

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`
`7`	`7`	`import FileSystem`
`8`	`8`	`import semmle.code.java.Element`
`9`		`-import semmle.code.SMAP`
	`9`	`+private import semmle.code.SMAP`
`10`	`10`
`11`	`11`	/** Holds if element `e` has name `name`. */
`12`	`12`	`predicate hasName(Element e, string name) {`
`@@ -72,7 +72,7 @@ class Top extends @top {`
`72`	`72`	`)`
`73`	`73`	`}`
`74`	`74`
`75`		`- predicate hasLocationInfoAux(`
	`75`	`+ private predicate hasLocationInfoAux(`
`76`	`76`	`string filepath, int startline, int startcolumn, int endline, int endcolumn`
`77`	`77`	`) {`
`78`	`78`	`exists(File f, Location l \| fixedHasLocation(this, l, f) \|`