diff --git a/core/dbobjectsearch.class.php b/core/dbobjectsearch.class.php
index 0b17f05c17..ad8a00620b 100644
--- a/core/dbobjectsearch.class.php
+++ b/core/dbobjectsearch.class.php
@@ -1134,6 +1134,14 @@ class DBObjectSearch extends DBSearch
 		return $this->m_oSearchCondition->ApplyParameters(array_merge($this->m_aParams, $aArgs));
 	}
 
+    /**
+     *
+     * @todo: check if the clone is mandatory or optional. (the performance would be better without cloning)
+     *
+     * @param bool $bClone
+     *
+     * @return DBObjectSearch|DBSearch
+     */
 	public function ShorthandExpansion($bClone = false)
     {
         if ($bClone)
@@ -1222,7 +1230,7 @@ class DBObjectSearch extends DBSearch
         $this->m_oSearchCondition->Browse($callback);
 
         //replace the ExternalFieldExpression by a FieldExpression (based on last ExternalFieldExpression::$aFields)
-        $this->m_oSearchCondition->Translate(array(), false, false);
+        $this->m_oSearchCondition->Translate(array(), false, false);//TODO: check if this call is correct
 
         return $oDbObject;
     }
diff --git a/core/oql/expression.class.inc.php b/core/oql/expression.class.inc.php
index 10d546ff77..df654a5660 100644
--- a/core/oql/expression.class.inc.php
+++ b/core/oql/expression.class.inc.php
@@ -841,6 +841,13 @@ class FalseExpression extends ScalarExpression
 	}
 }
 
+
+/**
+ * Class ExternalFieldExpression
+ *
+ * @todo verify if all required methods are implemented (ie: at first I missed the `Render` method, so  DBObjectSearch::toOQL() result was wrong)
+ *
+ */
 class ExternalFieldExpression extends UnaryExpression
 {
     /**
@@ -869,14 +876,21 @@ class ExternalFieldExpression extends UnaryExpression
         return $this->m_aFields;
     }
 
+    /**
+     * used by DBObjectSearch::ShorthandExpansion(). it result in the ExternalFieldExpression being replaced by a FieldExpression mathching the final entry in self::$m_aFields
+     *
+     * @param array $aTranslationData
+     * @param bool  $bMatchAll
+     * @param bool  $bMarkFieldsAsResolved
+     *
+     * @return Expression|FieldExpression|UnaryExpression
+     */
     public function Translate($aTranslationData, $bMatchAll = true, $bMarkFieldsAsResolved = true)
     {
         $aFields = $this->GetFields();
         $aLastField = end($aFields);
 
-
         $oRet = new FieldExpression($aLastField['sAttCode'], $aLastField['sAlias']);
-//        $oRet->Translate($aTranslationData, $bMatchAll, $bMarkFieldsAsResolved);
 
         return $oRet;
     }