Improve comments about Fields

Author: owen-mc

go/ql/lib/semmle/go/AST.qll

@@ -194,24 +194,27 @@ class DeclParent extends @declparent, AstNode {
 }
 
 /**
- * An AST node whose children include fields.
+ * An AST node whose children include field declarations.
+ *
+ * A field declaration can be in a struct, a function (for parameter or result
+ * variables), or an interface (in which case it is a method or embedding spec).
  */
 class FieldParent extends @fieldparent, AstNode {
   /**
-   * Gets the `i`th field of this node.
+   * Gets the `i`th field declaration of this node.
    *
-   * Note that the precise indices of fields are considered an implementation detail
-   * and are subject to change without notice.
+   * Note that the precise indices of field declarations are considered an
+   * implementation detail and are subject to change without notice.
    */
   FieldBase getField(int i) { fields(result, this, i) }
 
   /**
-   * Gets a child field of this node in the AST.
+   * Gets a child field declaration of this node in the AST.
    */
   FieldBase getAField() { result = this.getField(_) }
 
   /**
-   * Gets the number of child fields of this node.
+   * Gets the number of child field declarations of this node.
    */
   int getNumFields() { result = count(this.getAField()) }
 }

go/ql/lib/semmle/go/Decls.qll

@@ -416,8 +416,19 @@ class AliasSpec extends @aliasspec, TypeSpec { }
 class TypeDefSpec extends @typedefspec, TypeSpec { }
 
 /**
- * A field declaration, of a struct, a function (in which case this is a parameter or result variable),
- * or an interface (in which case this is a method or embedding spec).
+ * A field declaration, in a struct, a function (for parameter or result
+ * variables), or an interface (in which case this is a method or embedding
+ * spec).
+ *
+ * Examples:
+ *
+ * ```go
+ * s string
+ * x, y int
+ * Close() error
+ * io.Reader
+ * ~int | float32
+ * ```
  */
 class FieldBase extends @field, ExprParent {
   /**
@@ -433,6 +444,13 @@ class FieldBase extends @field, ExprParent {
 
 /**
  * A field declaration in a struct type.
+ *
+ * Examples:
+ *
+ * ```go
+ * Name string `json:"name"`
+ * x, y int
+ * ```
  */
 class FieldDecl extends FieldBase, Documentable, ExprParent {
   StructTypeExpr st;
@@ -464,6 +482,12 @@ class FieldDecl extends FieldBase, Documentable, ExprParent {
 
 /**
  * An embedded field declaration in a struct.
+ *
+ * Examples:
+ *
+ * ```go
+ * io.Reader
+ * ```
  */
 class EmbeddedFieldDecl extends FieldDecl {
   EmbeddedFieldDecl() { not exists(this.getNameExpr(_)) }
@@ -473,6 +497,13 @@ class EmbeddedFieldDecl extends FieldDecl {
 
 /**
  * A function parameter or result variable declaration.
+ *
+ * Examples:
+ *
+ * ```go
+ * name string
+ * x, y int
+ * ```
  */
 class ParameterOrResultDecl extends FieldBase, Documentable, ExprParent {
   int rawIndex;
@@ -507,6 +538,13 @@ class ParameterOrResultDecl extends FieldBase, Documentable, ExprParent {
 
 /**
  * A parameter declaration.
+ *
+ * Examples:
+ *
+ * ```go
+ * name string
+ * x, y int
+ * ```
  */
 class ParameterDecl extends ParameterOrResultDecl {
   ParameterDecl() { rawIndex >= 0 }
@@ -524,6 +562,13 @@ class ParameterDecl extends ParameterOrResultDecl {
 
 /**
  * A receiver declaration in a function declaration.
+ *
+ * Examples:
+ *
+ * ```go
+ * p *Point
+ * r io.Reader
+ * ```
  */
 class ReceiverDecl extends FieldBase, Documentable, ExprParent {
   FuncDecl fd;
@@ -547,6 +592,14 @@ class ReceiverDecl extends FieldBase, Documentable, ExprParent {
 
 /**
  * A result variable declaration.
+ *
+ * Examples:
+ *
+ * ```go
+ * error
+ * r io.Reader
+ * x, y int
+ * ```
  */
 class ResultVariableDecl extends ParameterOrResultDecl {
   ResultVariableDecl() { rawIndex < 0 }
@@ -564,6 +617,15 @@ class ResultVariableDecl extends ParameterOrResultDecl {
 
 /**
  * A type parameter declaration in a type specification.
+ *
+ * Examples:
+ *
+ * ```go
+ * T any
+ * S, T comparable
+ * K ~int32 | float32
+ * _ any
+ * ```
  */
 class TypeParamDecl extends @typeparamdecl, Documentable, ExprParent {
   TypeParamDecl() { typeparamdecls(this, _, _) }
@@ -615,6 +677,14 @@ class TypeParamDecl extends @typeparamdecl, Documentable, ExprParent {
 
 /**
  * A method or embedding specification in an interface type expression.
+ *
+ * Examples:
+ *
+ * ```go
+ * Read([]byte) (int, error)
+ * io.Reader
+ * ~int32 | float32
+ * ```
  */
 class InterfaceMemberSpec extends FieldBase, Documentable, ExprParent {
   InterfaceTypeExpr ite;
@@ -636,6 +706,12 @@ class InterfaceMemberSpec extends FieldBase, Documentable, ExprParent {
 
 /**
  * A method specification in an interface.
+ *
+ * Examples:
+ *
+ * ```go
+ * Read([]byte) (int, error)
+ * ```
  */
 class MethodSpec extends InterfaceMemberSpec {
   Expr name;
@@ -654,6 +730,13 @@ class MethodSpec extends InterfaceMemberSpec {
 
 /**
  * An embedding specification in an interface.
+ *
+ * Examples:
+ *
+ * ```go
+ * io.Reader
+ * ~int32 | float32
+ * ```
  */
 class EmbeddingSpec extends InterfaceMemberSpec {
   EmbeddingSpec() { not exists(this.getChildExpr(1)) }