address comment: add comments

Author: mgaido91

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/Expression.scala

@@ -199,16 +199,27 @@ abstract class Expression extends TreeNode[Expression] {
    * cosmetically (i.e. capitalization of names in attributes may be different).
    *
    * See [[Canonicalize]] for more details.
+   *
+   * This method should be used (instead of `sameResult`) when comparing if 2 expressions are the
+   * same and one can replace the other (eg. in Optimizer/Analyzer rules when we want to replace
+   * equivalent expressions). It should not be used (and `sameResult` should be used instead) when
+   * comparing if 2 expressions produce the same output (in this case `semanticEquals` can be too
+   * strict).
    */
   def semanticEquals(other: Expression): Boolean =
     deterministic && other.deterministic && canonicalized == other.canonicalized
 
   /**
    * Returns true when two expressions will always compute the same result, even if the output may
    * be different, because of different names or similar differences.
-   * Usually this means they their canonicalized form equals, but it may also not be the case, as
+   * Usually this means that their canonicalized form equals, but it may also not be the case, as
    * different output expressions can evaluate to the same result as well (eg. when an expression
    * is aliased).
+   *
+   * This method should be used (instead of `semanticEquals`) when checking if 2 expressions
+   * produce the same output (eg. as in the case we are interested to check if the ordering is the
+   * same). It should not be used (and `semanticEquals` should be used instead) when comparing if 2
+   * expressions are the same and one can replace the other.
    */
   def sameResult(other: Expression): Boolean = other match {
     case a: Alias => sameResult(a.child)