Rework comments for some CPG properties.

Added/adjuted comments for METHOD_FULL_NAME, TYPE_FULL_NAME,
DYNAMIC_TYPE_HINT_FULL_NAME.

Author: ml86

schema/src/main/scala/io/shiftleft/codepropertygraph/schema/CallGraph.scala

@@ -55,8 +55,18 @@ object CallGraph extends SchemaBase {
       .addProperty(
         name = "METHOD_FULL_NAME",
         valueType = ValueType.String,
-        comment = """The FULL_NAME of a method. Used to link CALL and METHOD nodes. It is required
-                    |to have exactly one METHOD node for each METHOD_FULL_NAME""".stripMargin
+        comment = """The FULL_NAME of a method. Used to link CALL and METHOD nodes.
+                    |For METHOD nodes this property must be a unique fully-qualified name.
+                    |For CALL nodes this property has different semantics depending on the
+                    |CALL nodes DISPATCH_TYPE property.
+                    |For DISPATCH_TYPE STATIC_DISPATCH this property contains the
+                    |fully-qualified name of the called method.
+                    |For DISPATCH_TYPE DYNAMIC_DISPATCH this property contains the
+                    |fully-qualified name of the assured interface method which is
+                    |straight forward for statically typed languages like Java and CSharp.
+                    |For dynamically typed languages no interface assurance exists so
+                    |frontends should indicate by some name like "<unknown>".
+                    |""".stripMargin
       )
       .mandatory(PropertyDefaults.String)
       .protoId(54)

schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Hidden.scala

@@ -155,7 +155,15 @@ object Hidden extends SchemaBase {
       .addProperty(
         name = "DYNAMIC_TYPE_HINT_FULL_NAME",
         valueType = ValueType.String,
-        comment = "Type hint for the dynamic type"
+        comment =
+          """This is a multi valued property which gives information about all observable
+            |runtime types for the node carrying this property. This means if e.g. an
+            |expression has the static TYPE_FULL_NAME `SomeInterface` which is implemented
+            |by `ImplA`, `ImplB` and `ImplC` and DYNAMIC_TYPE_HINT_FULL_NAME is given as
+            |`List(ImplA, ImplB)`, that only `ImplA` and `ImplB` can ever be observed
+            |as runtime times and never `ImplC`. This property is used to enable shortcuts
+            |in data flow tracker implementations.
+            |""".stripMargin
       )
       .asList()
       .protoId(1591)

schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Type.scala

@@ -31,9 +31,23 @@ object Type extends SchemaBase {
         name = "TYPE_FULL_NAME",
         valueType = ValueType.String,
         comment = """This field contains the fully-qualified static type name of the program
-                    |construct represented by a node. It is the name of an instantiated type, e.g.,
-                    |`java.util.List<Integer>`, rather than `java.util.List[T]`. If the type
-                    |cannot be determined, this field should be set to the empty string.
+                    |construct represented by a node. For static languages like Java and CSharp
+                    |this property is supposed to be filled with type names guaranteed to be
+                    |correct. E.g. type names coming from a compiler library or byte code.
+                    |Dynamic languages have no static type information and are supposed
+                    |to fill this property with always the same type name which indicates "any".
+                    |This is why for example for Javascript the type name "ANY" is used.
+                    |Type full names for higher kinded types like `java.util.List<T>` can
+                    |appear with or without a concrete types for `T`. Two examples for Java
+                    |illustrate this:
+                    |  1. `List<Integer> l = null`
+                    |     Here the IDENTIFIER and LOCAL nodes for `l` have `java.lang.List<T>`
+                    |     as type full name.
+                    |  2. `class SomeGenericClass<A> { void doStuff(List<A> par1) { ... } }`
+                    |     Here the METHOD_PARAMETER_IN node for `par` has `java.lang.List<A>`
+                    |     as type full name.
+                    |If the type cannot be determined, use some indicative name reflecting this
+                    |fact like "<unresolved>".
                     |""".stripMargin
       )
       .mandatory(PropertyDefaults.String)