..
    ----------------------------------------------------------------------------------------------
     Copyright (c) The Einsums Developers. All rights reserved.
     Licensed under the MIT License. See LICENSE.txt in the project root for license information.
    ----------------------------------------------------------------------------------------------


.. _cppapi_DocComment:

==========
DocComment
==========

.. note::
   Generated from the C++ headers by ``apiary --emit-cpp-docs-json``.

.. cpp:namespace:: apiary

.. cpp:class:: DocComment

   Structured form of a doc comment.

   Every text field is reST-ready: inline Doxygen commands (`@c`, `@p`, `@ref`,
   `:math:`math``, ...) are converted and block constructs (`@code`,
   `@versionadded`, `@note`, ...) are rendered as reST directives inside
   `detail`.


   .. cpp:function:: bool empty()

      Whether every field is empty.

      :returns: `true` if brief, detail, params, tparams, returns, and throws are all empty.


   .. cpp:member:: std::string brief

      One-line summary (from @brief or leading paragraph).


   .. cpp:member:: std::string detail

      Remaining prose + converted block directives.


   .. cpp:member:: std::vector<DocEntry> params


      :param entries.:


   .. cpp:member:: std::vector<DocEntry> tparams


      :tparam entries: (C++ template params; usually omitted from Python pages).


   .. cpp:member:: std::string returns


      :returns: / @returns text.


   .. cpp:member:: std::vector<DocEntry> throws_


      :throws /: @throw / @exception entries (name = exception type).



.. cpp:class:: DocEntry

   A named doc entry: @param / @tparam / @throws.

   `name` is the parameter or exception-type name; `description` is reST-ready
   text (inline commands already converted).


   .. cpp:member:: std::string name

      The parameter or exception-type name.


   .. cpp:member:: std::string description

      reST-ready description text (inline commands already converted).



.. cpp:function:: DocComment parse_doc_comment(const std::string &raw)

   Parse a marker-stripped Doxygen comment body into structured form.

   :param raw: The marker-stripped Doxygen comment body.
   :returns: The structured DocComment.