From 8b5435ca48c6bd640a6eec6ae867a9423a73ade3 Mon Sep 17 00:00:00 2001 From: Cary Phillips Date: Mon, 20 Feb 2023 12:11:58 -0800 Subject: [PATCH] Fix documentation glitches and symbol visibility table (#294) Signed-off-by: Cary Phillips --- docs/SymbolVisibility.rst | 130 +++++++++++++++++++++++--------------- docs/index.rst | 8 +-- 2 files changed, 83 insertions(+), 55 deletions(-) diff --git a/docs/SymbolVisibility.rst b/docs/SymbolVisibility.rst index 0564d42d..b61fc314 100644 --- a/docs/SymbolVisibility.rst +++ b/docs/SymbolVisibility.rst @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-3-Clause Copyright Contributors to the OpenEXR Project. -.. _Symbol Visibility in OpenEXR: +.. _Symbol Visibility in Imath/OpenEXR: Symbol Visibility in Imath/OpenEXR ################################## @@ -63,61 +63,89 @@ it also exports the types for the member types as well, which is not desired, so these are marked as N/A even though the compiler does allow that to happen. - -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| C++ vs Compiler | MSVC | mingw | gcc | clang | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| function | ``dllexport/dllimport`` | ``dllexport/dllimport`` | ``visibility("default")`` | ``visibility("default")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| hide a function | N/A | N/A | ``visibility("hidden")`` | ``visibility("hidden")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| ``class(typeinfo)`` | N/A | N/A | ``visibility("default")`` | ``visibility("default")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| template class | N/A | N/A | ``visibility("default")`` | ``type_visibility("default")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| template data | N/A | N/A | ``visibility("default")`` | ``visibility("default")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| class template
instantiation | ``dllexport/dllimport`` | N/A | N/A | ``visibility("default")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| enum | N/A | N/A | auto unhides (N/A) | ``type_visibility("default")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ -| extern template | N/A | ``dllexport/dllimport`` | ``visibility("default")`` | ``visibility("default")`` | -+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+ +.. list-table:: + :header-rows: 1 + :align: left + + * - C++ vs Compiler + - MSVC + - mingw + - gcc + - clang + * - function + - ``dllexport/dllimport`` + - ``dllexport/dllimport`` + - ``visibility("default")`` + - ``visibility("default")`` + * - hide a function + - N/A + - N/A + - ``visibility("hidden")`` + - ``visibility("hidden")`` + * - ``class(typeinfo)`` + - N/A + - N/A + - ``visibility("default")`` + - ``visibility("default")`` + * - template class + - N/A + - N/A + - ``visibility("default")`` + - ``type_visibility("default")`` + * - template data + - N/A + - N/A + - ``visibility("default")`` + - ``visibility("default")`` + * - class template instantiation + - ``dllexport/dllimport`` + - N/A + - N/A + - ``visibility("default")`` + * - enum + - N/A + - N/A + - auto unhides (N/A) + - ``type_visibility("default")`` + * - extern template + - N/A + - ``dllexport/dllimport`` + - ``visibility("default")`` + - ``visibility("default")`` With this matrix in mind, we can see the maximal set of macros we need to provide throughout the code. *NB*: This does not mean that we need to -declare all of these, just that they might be needed. `XXX` should be -substituted for the particular library name being compiled. - -+----------------------------------+------------------------------------------------------------------+ -| macro name | purpose | -+----------------------------------+------------------------------------------------------------------+ -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_EXPORT`` | one of export or import for windows, visibility for others | -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_EXPORT_TYPE`` | for declaring a class / struct as public (for typeinfo / vtable) | -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_HIDDEN`` | used to explicitly hide, especially members of types | -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_EXPORT_TEMPLATE_TYPE`` | stating the template type should be visible | -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_EXPORT_EXTERN_TEMPLATE`` | exporting template types (i.e. extern side of extern template) | -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_EXPORT_TEMPLATE_INSTANCE`` | exporting specific template instantiations (in cpp code) | -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_EXPORT_TEMPLATE_DATA`` | exporting templated data blocks | -+----------------------------------+------------------------------------------------------------------+ -| ``XXX_EXPORT_ENUM`` | exporting enum types | -+----------------------------------+------------------------------------------------------------------+ - -For a new library, the preference might be to call ``XXX_EXPORT`` -something like ``XXX_FUNC``, and rename things such as ``XXX_EXPORT_TYPE`` -to ``XXX_TYPE`` for simplicity. However, historically, OpenEXR has used +declare all of these, just that they might be needed. + +.. list-table:: + :header-rows: 1 + :align: left + + * - macro name + - purpose + * - ``IMATH_EXPORT`` + - one of export or import for windows, visibility for others + * - ``IMATH_EXPORT_TYPE`` + - for declaring a class / struct as public (for typeinfo / vtable) + * - ``IMATH_HIDDEN`` + - used to explicitly hide, especially members of types + * - ``IMATH_EXPORT_TEMPLATE_TYPE`` + - stating the template type should be visible + * - ``IMATH_EXPORT_EXTERN_TEMPLATE`` + - exporting template types (i.e. extern side of extern template) + * - ``IMATH_EXPORT_TEMPLATE_INSTANCE`` + - exporting specific template instantiations (in cpp code) + * - ``IMATH_EXPORT_TEMPLATE_DATA`` + - exporting templated data blocks + * - ``IMATH_EXPORT_ENUM`` + - exporting enum types + +The preference might be to call ``IMATH_EXPORT`` something like +``IMATH_FUNC``, and rename things such as ``IMATH_EXPORT_TYPE`` to +``IMATH_TYPE`` for simplicity. However, historically, OpenEXR has used the ``_EXPORT`` tag, and so that is preserved for consistency. -References -========== +--------- * LLVM libc++ visibility macros: https://libcxx.llvm.org/docs/DesignDocs/VisibilityMacros.html diff --git a/docs/index.rst b/docs/index.rst index 7d2d96e7..389683e0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,11 +4,11 @@ .. _Overview: -Overview -######## +Imath +##### .. toctree:: - :caption: Overview + :caption: Imath :maxdepth: 1 Imath is a basic, light-weight, and efficient C++ representation of 2D @@ -50,7 +50,7 @@ Community * **Contribute a Fix, Feature, or Improvement:** - - Read the `Contribution guidelines + - Read the `Contribution Guidelines `_ and `Code of Conduct `_