C++/Java/JavaScript/Python: Make qldoc consistent.

Max Schaefer · Max Schaefer · commit 923e36ba4fa1 · 2019-12-17T10:15:43.000Z
diff --git a/cpp/ql/src/semmle/code/cpp/XML.qll b/cpp/ql/src/semmle/code/cpp/XML.qll
@@ -10,8 +10,11 @@ abstract class XMLLocatable extends @xmllocatable {
   Location getLocation() { xmllocations(this, result) }
 
   /**
-   * Holds if this element has the specified location information,
-   * including file path, start line, start column, end line and end column.
+   * Holds if this element is at the specified location.
+   * The location spans column `startcolumn` of line `startline` to
+   * column `endcolumn` of line `endline` in file `filepath`.
+   * For more information, see
+   * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
    */
   predicate hasLocationInfo(
     string filepath, int startline, int startcolumn, int endline, int endcolumn
@@ -22,7 +25,7 @@ abstract class XMLLocatable extends @xmllocatable {
     )
   }
 
-  /** Gets a printable representation of this element. */
+  /** Gets a textual representation of this element. */
   abstract string toString();
 }
 
@@ -135,7 +138,17 @@ class XMLFile extends XMLParent, File {
   XMLDTD getADTD() { xmlDTDs(result, _, _, _, this) }
 }
 
-/** A "Document Type Definition" of an XML file. */
+/**
+ * An XML document type definition (DTD).
+ *
+ * Example:
+ *
+ * ```
+ * <!ELEMENT person (firstName, lastName?)>
+ * <!ELEMENT firstName (#PCDATA)>
+ * <!ELEMENT lastName (#PCDATA)>
+ * ```
+ */
 class XMLDTD extends @xmldtd {
   /** Gets the name of the root element of this DTD. */
   string getRoot() { xmlDTDs(this, result, _, _, _) }
@@ -162,7 +175,17 @@ class XMLDTD extends @xmldtd {
   }
 }
 
-/** An XML tag in an XML file. */
+/**
+ * An XML element in an XML file.
+ *
+ * Example:
+ *
+ * ```
+ * <manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ *           package="com.example.exampleapp" android:versionCode="1">
+ * </manifest>
+ * ```
+ */
 class XMLElement extends @xmlelement, XMLParent, XMLLocatable {
   /** Holds if this XML element has the given `name`. */
   predicate hasName(string name) { name = getName() }
@@ -207,7 +230,16 @@ class XMLElement extends @xmlelement, XMLParent, XMLLocatable {
   override string toString() { result = XMLParent.super.toString() }
 }
 
-/** An attribute that occurs inside an XML element. */
+/**
+ * An attribute that occurs inside an XML element.
+ *
+ * Examples:
+ *
+ * ```
+ * package="com.example.exampleapp"
+ * android:versionCode="1"
+ * ```
+ */
 class XMLAttribute extends @xmlattribute, XMLLocatable {
   /** Gets the name of this attribute. */
   string getName() { xmlAttrs(this, _, result, _, _, _) }
@@ -228,7 +260,15 @@ class XMLAttribute extends @xmlattribute, XMLLocatable {
   override string toString() { result = this.getName() + "=" + this.getValue() }
 }
 
-/** A namespace used in an XML file */
+/**
+ * A namespace used in an XML file.
+ *
+ * Example:
+ *
+ * ```
+ * xmlns:android="http://schemas.android.com/apk/res/android"
+ * ```
+ */
 class XMLNamespace extends @xmlnamespace {
   /** Gets the prefix of this namespace. */
   string getPrefix() { xmlNs(this, result, _, _) }
@@ -247,7 +287,15 @@ class XMLNamespace extends @xmlnamespace {
   }
 }
 
-/** A comment of the form `<!-- ... -->` is an XML comment. */
+/**
+ * A comment in an XML file.
+ *
+ * Example:
+ *
+ * ```
+ * <!-- This is a comment. -->
+ * ```
+ */
 class XMLComment extends @xmlcomment, XMLLocatable {
   /** Gets the text content of this XML comment. */
   string getText() { xmlComments(this, result, _, _) }
@@ -262,6 +310,12 @@ class XMLComment extends @xmlcomment, XMLLocatable {
 /**
  * A sequence of characters that occurs between opening and
  * closing tags of an XML element, excluding other elements.
+ *
+ * Example:
+ *
+ * ```
+ * <content>This is a sequence of characters.</content>
+ * ```
  */
 class XMLCharacters extends @xmlcharacters, XMLLocatable {
   /** Gets the content of this character sequence. */
diff --git a/java/ql/src/semmle/code/xml/XML.qll b/java/ql/src/semmle/code/xml/XML.qll
@@ -88,7 +88,10 @@ class XMLParent extends @xmlparent {
     )
   }
 
-  /** Append all the character sequences of this XML parent from left to right, separated by a space. */
+  /**
+   * Gets the result of appending all the character sequences of this XML parent from
+   * left to right, separated by a space.
+   */
   string allCharactersString() {
     result = concat(string chars, int pos |
         xmlChars(_, chars, this, pos, _, _)
diff --git a/javascript/ql/src/semmle/javascript/XML.qll b/javascript/ql/src/semmle/javascript/XML.qll
@@ -88,7 +88,10 @@ class XMLParent extends @xmlparent {
     )
   }
 
-  /** Append all the character sequences of this XML parent from left to right, separated by a space. */
+  /**
+   * Gets the result of appending all the character sequences of this XML parent from
+   * left to right, separated by a space.
+   */
   string allCharactersString() {
     result = concat(string chars, int pos |
         xmlChars(_, chars, this, pos, _, _)
diff --git a/python/ql/src/semmle/python/xml/XML.qll b/python/ql/src/semmle/python/xml/XML.qll

Original file line number	Diff line number	Diff line change
`@@ -88,7 +88,10 @@ class XMLParent extends @xmlparent {`
`88`	`88`	`)`
`89`	`89`	`}`
`90`	`90`
`91`		`- /** Append all the character sequences of this XML parent from left to right, separated by a space. */`
	`91`	`+ /**`
	`92`	`+ * Gets the result of appending all the character sequences of this XML parent from`
	`93`	`+ * left to right, separated by a space.`
	`94`	`+ */`
`92`	`95`	`string allCharactersString() {`
`93`	`96`	`result = concat(string chars, int pos \|`
`94`	`97`	`xmlChars(_, chars, this, pos, _, _)`