add text on symbol visibility

Signed-off-by: Thomas Naughton <[email protected]>
Co-authored-by: Jeff Squyres <[email protected]>

Author: naughtont3

docs/developers/source-code.rst

@@ -263,3 +263,30 @@ of the |ompi_series| source tree):
 
 Under these mandated directories, frameworks and/or components may have
 arbitrary directory structures, however.
+
+Symbol Visibility
+-----------------
+
+The ``*_DECLSPEC`` macros provide a method to annotate symbols to indicate
+their intended visibility when compiling dynamically shared object files
+(e.g., ``libmpi.so``).  The macros are defined on a per project basis:
+
+* Open MPI: ``OMPI_DECLSPEC``
+* Open PAL: ``OPAL_DECLSPEC``
+* OpenSHMEM: ``OSHMEM_DECLSPEC``
+
+The macros expand to the appropriate compiler and platform flags for marking
+whether a symbol should be explicitly made public in the target project's
+library namespace.
+The ``*_DECLSPEC`` attributes are used to declare that a symbol is to be
+visible outside of that library/DSO's scope.  For example, ``OMPI_DECLSPEC``
+is used to control what symbols are visible in the ``libmpi.so`` scope.
+
+.. note:: This is entirely related to dynamic library compilation and does not
+   apply to static compilation.
+
+.. note:: The macros were originally introduced when Open MPI supported
+   Windows (circa Open MPI v1.0.0) and are motivated by the Windows
+   `__declspec <https://docs.microsoft.com/en-us/cpp/cpp/declspec?view=msvc-170>`_.
+   While support for Windows has been dropped from Open MPI, the symbol
+   visibility macros remain.