The Property Tree
=================

A fundamental structure in FlightGear is the :dfn:`property tree`. This is a
data structure formed from :cpp:class:`SGPropertyNode` instances. FlightGear
has a global Property Tree, which is the one visible in the
`Property Browser`_ and containing nodes such as ``/sim/aircraft``. The C++
and Nasal code also uses many “local” property trees, which are simply trees
of :cpp:class:`SGPropertyNode` instances.

.. _Property Browser: https://wiki.flightgear.org/Property_browser

How to reference C++ overloads is explained `in the Sphinx manual`__:

.. __: https://www.sphinx-doc.org/en/master/usage/domains/cpp.html#overloaded-member-functions

- :literal:`cpp:func:\`SGPropertyNode::alias\`` as well as
  :literal:`cpp:func:\`SGPropertyNode::alias()\`` reference an arbitrary
  overload of ``SGPropertyNode::alias()``: :cpp:func:`SGPropertyNode::alias`;

- :literal:`cpp:func:\`bool SGPropertyNode::alias(SGPropertyNode* target, bool withListener)\``
  references a specific overload:
  :cpp:func:`bool SGPropertyNode::alias(SGPropertyNode* target, bool withListener)`;

- ditto for the other overloads
  :cpp:func:`bool SGPropertyNode::alias(const char* path, bool withListener)` and
  :cpp:func:`bool SGPropertyNode::alias(const std::string& path, bool withListener)`.

Doxygen has a `grouping feature
<https://www.doxygen.nl/manual/grouping.html>`__ to avoid repeating the same
documentation for similar overloads and Breathe is `supposed to support it
<https://breathe.readthedocs.io/en/latest/groups.html>`__, however I didn't
manage to use it successfully here (there was an XML file named
``xml/df/dc0/group__MyGroupNameHere.xml`` with seemingly good data in the
Doxygen output, however my :literal:`cpp:func:\`...\`` for the groupped
overloads pointed nowhere).

.. toctree::
   :maxdepth: 2
   :caption: Classes

   classes/SGPropertyNode