Doc: Improve App::DocumentObject documentation

It also improves documentation from other files for relevant dependent
functions.

src/App/Application.h

@@ -461,16 +461,18 @@ public:
     /** @name Link handling */
     //@{
 
-    /** Check for link recursion depth
+    /**
+     * @brief Check for link recursion depth.
+     *
+     * The function uses an internal count of all objects in all documents as
+     * the limit of recursion depth.  If the depth exceeds this limit, it means
+     * that there is likely a cyclic reference in the links.
      *
      * @param depth: current depth
      * @param option: whether to throw exception, print an error message or quieten any output.
      * In the latter case the caller must check the returned value.
      *
      * @return Return the maximum remaining depth.
-     *
-     * The function uses an internal count of all objects in all documents as
-     * the limit of recursion depth.
      */
     int checkLinkDepth(int depth, MessageOption option = MessageOption::Error);
 

src/App/DocumentObject.cpp

@@ -616,7 +616,7 @@ bool DocumentObject::isInOutListRecursive(DocumentObject* linkTo) const
 }
 
 std::vector<std::list<App::DocumentObject*>>
-DocumentObject::getPathsByOutList(App::DocumentObject* to) const
+DocumentObject::getPathsByOutList(const App::DocumentObject* to) const
 {
     return _pDoc->getPathsByOutList(this, to);
 }

src/App/DocumentObjectExtension.h

@@ -97,10 +97,31 @@ public:
      */
     virtual bool extensionGetSubObjects(std::vector<std::string>& ret, int reason) const;
 
-    /** Get the linked object
-     *  @sa DocumentObject::getLinkedObject()
+    /**
+     * @brief Get the linked object of this extension.
      *
-     * @return Return turn if handled, the linked object is returned in \c ret
+     * This method returns the linked object of this document object.  If there
+     * is no linked object, it will return the container object of the
+     * extension.
+     *
+     * @param[out] ret The linked object is returned in this parameter.
+     *
+     * @param[in] recurse If true, it will recursively resolve the link until it
+     * reaches the final linked object.
+     *
+     * @param mat[in,out] If non-null, it is used as the current transformation
+     * matrix on input. On output it is used as the accumulated transformation
+     * up until the final linked object.
+     *
+     * @param[in] transform If false, then it will not accumulate the object's own
+     * placement into @p mat, which lets you override the object's placement.
+     *
+     * @param[in] depth This parameter indicates the level on which we are
+     * resolving the link.
+     *
+     * @return Returns true if the linked object is successfully retrieved and
+     * returned in @p ret. If the linked object is not found or is invalid, it
+     * returns false.
      */
     virtual bool extensionGetLinkedObject(DocumentObject*& ret,
                                           bool recursive,

src/App/Link.h

@@ -341,6 +341,17 @@ public:
     const char* flattenSubname(const char* subname) const;
     void expandSubname(std::string& subname) const;
 
+    /**
+     * @brief Get the object the link points to.
+     *
+     * This method returns the linked object of this link. The @p depth
+     * parameter is used as an indication of how deep the recursion is as a
+     * safeguard against infinite recursion caused by cyclic dependencies.
+     *
+     * @param[in] depth The level on which we are resolving the link.
+     *
+     * @return Returns the linked object or @c nullptr if there is no linked value.
+     */
     DocumentObject* getLink(int depth = 0) const;
 
     Base::Matrix4D getTransform(bool transform) const;
@@ -403,6 +414,33 @@ public:
                  const char* subname = nullptr,
                  const std::vector<std::string>& subs = std::vector<std::string>());
 
+    /**
+     * @brief Get the true linked object.
+     *
+     * This method returns the true linked object, which is the object that the
+     * link points to.  The @p depth parameter is used as an indication of the
+     * current level of recursion is as a safeguard against infinite recursion
+     * caused by cyclic dependencies.
+     *
+     * @param recurse If true, it will recursively resolve the link until it reaches
+     * the final linked object, or until it reaches the maximum recursion depth.
+     *
+     * @param mat If non-null, it is used as the current transformation matrix on
+     * input. On output it is used as the accumulated transformation up until
+     * the final linked object.
+     *
+     * @param depth This parameter indicates the level on which we are
+     * resolving the link.
+     *
+     * @param noElement If true, it will not return the linked object if it is
+     * a link to an element.
+     *
+     * @return Returns the true linked object. If the linked object is not found
+     * or is invalid, it returns @c nullptr.
+     *
+     * @sa DocumentObject::getLinkedObject() which may return itself if it is not a link.
+     *
+     */
     DocumentObject* getTrueLinkedObject(bool recurse,
                                         Base::Matrix4D* mat = nullptr,
                                         int depth = 0,

src/App/PropertyExpressionEngine.h

@@ -100,7 +100,6 @@ public:
     /**
      * @brief The ExpressionInfo struct encapsulates an expression.
      */
-
     struct ExpressionInfo
     {
         std::shared_ptr<App::Expression> expression; /**< The actual expression tree */

src/App/PropertyLinks.h

@@ -262,14 +262,20 @@ public:
         return nullptr;
     }
 
-    /** Update object label reference in this property
+    /**
+     * @brief Update the object label reference of this property.
      *
-     * @param obj: the object owner of the changing label
-     * @param ref: subname reference to old label
-     * @param newLabel: the future new label
+     * This method does not update the property itself, but returns a copy of
+     * the property with the updated label reference if the property is
+     * affected.  The copy will later be assigned to this property by calling its
+     * Paste() method.
      *
-     * @return Returns a copy of the property if its link reference is affected.
-     * The copy will later be assgiend to this property by calling its Paste().
+     * @param[in] obj The object owner of the changing label.
+     * @param[in] ref The subname reference to old label.
+     * @param[in] newLabel The future new label.
+     *
+     * @return A copy of the property if its link reference is affected,
+     * otherwise `nullptr`.
      */
     virtual Property*
     CopyOnLabelChange(App::DocumentObject* obj, const std::string& ref, const char* newLabel) const
@@ -556,13 +562,17 @@ public:
      */
     static void getLabelReferences(std::vector<std::string>& labels, const char* subname);
 
-    /** Helper function to collect changed property when an object re-label
+    /**
+     * @brief Update label references on label change of a document object.
      *
-     * @param obj: the object that owns the label
-     * @param newLabel: the new label
+     * This helper function collects changed properties when an object re-label
+     * takes place.  It returns a map from affected properties to copies of
+     * those affectedd propertiess with updated subname references.
      *
-     * @return return a map from the affected property to a copy of it with
-     * updated subname references
+     * @param[in] obj The object that owns the label that is changed.
+     * @param[in] newLabel The new label of the object.
+     *
+     * @return The map from affected property to a copy of it.
      */
     static std::vector<std::pair<Property*, std::unique_ptr<Property>>>
     updateLabelReferences(App::DocumentObject* obj, const char* newLabel);