diff --git a/doc/main.h b/doc/main.h index c01855ccb..6c5592eec 100644 --- a/doc/main.h +++ b/doc/main.h @@ -2,6 +2,7 @@ * \file * Main page of the Doxygen-generated documentation. */ + /** * \mainpage ns-3 Documentation * @@ -70,6 +71,7 @@ * - wimax * */ + /** * \namespace ns3 * \brief Every class exported by the ns3 library is enclosed in the @@ -107,3 +109,12 @@ #define NS3_LOG_ENABLE /**@}*/ + +/** + * \page EnvironVar All Environment Variables + * + * All environment variables used by ns-3 are documented by module. + * + * \section environcore Core Enviroment Variables + * See \ref core-environ + */ diff --git a/src/core/doc/core.h b/src/core/doc/core.h index f4ed96e7f..bd95bebf9 100644 --- a/src/core/doc/core.h +++ b/src/core/doc/core.h @@ -81,3 +81,19 @@ * \defgroup core-tests Core module tests * TestSuites for the Core module */ + +/** + * \ingroup core + * \defgroup system System Services + * + * System-independent interfaces to operating system services: + * environment variables, files system, threading, wall clock time. + * + * Services provided: + * + * - Environment variables + * - File and directory paths. + * - Thread primitives: threads, conditional waits, mutex, critical sections. + * - Asynchronous input from a file descriptor. + * - Wall clock time. + */ diff --git a/src/core/doc/environment-variables.h b/src/core/doc/environment-variables.h new file mode 100644 index 000000000..3427fa1f1 --- /dev/null +++ b/src/core/doc/environment-variables.h @@ -0,0 +1,189 @@ +/* + * Copyright (c) 2022 Lawrence Livermore National Laboratory + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 as + * published by the Free Software Foundation; + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + * Author: Peter D. Barnes, Jr. + */ + +// This file supplies Doxygen documentation only. +// It should *NOT* be included in the build. + +/** + * \ingroup system + * \defgroup core-environ Environment Variables + */ + +/** + * \ingroup core-environ + * \brief Initialize an ns3::Attribute + * + * Sets a new default \pname{value} for an Attribute. + * This is invoked if the ns3::Object being constructed has an Attribute + * matching \pname{name}, and that Attribute didn't appear in the + * ns3::AttributeConstructionList argument to ns3::ObjectBase::ConstructSelf. + * The ns3::AttributeConstructionList is typically createad by an ns3::ObjectFactory + * and populated by ns3::ObjectFactory::Set. + * + * All objects with an Attribute matching \pname{name} will be matched, + * so name collisions could wreak havoc. + * + *
+ *
%Parameters
+ *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + *
nameThe name of the Attribute to set.
valueThe value to set the Attribute to.
;Multiple \pname{name}=\pname{value} pairs should be delimited by ';'
+ *
+ *
+ * + * Referenced by ns3::ObjectBase::ConstructSelf. + */ +const char* NS_ATTRIBUTE_DEFAULT = "name=value[;...]"; + +/** + * \ingroup core-environ + * \brief Write the ns3::CommandLine::Usage message, in Doxygen format, + * to the referenced location. + * + * Set the directory where ns3::CommandLine instances should write their Usage + * message, used when building documentation. + * + * This is used primarily by the documentation builds, which execute each + * registered example to gather their ns3::CommmandLine::Usage information. + * This wouldn't normally be useful to users. + * + *
+ *
%Parameters
+ *
+ * + * + * + * + * + *
path The directory where ns3::CommandLine should write its Usage message.
+ *
+ *
+ * + * Referenced by ns3::CommandLine::PrintDoxygenUsage. + */ +const char* NS_COMMANDLINE_INTROSPECTION = "path"; + +/** + * \ingroup core-environ + * \brief Initialize a ns3::GlobalValue. + * + * Initialize the ns3::GlobalValue \pname{name} from \pname{value}. + * + * This overrides the initial value set in the corresponding + * ns3::GlobalValue constructor. + * + *
+ *
%Parameters
+ *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + *
nameThe name of the ns3::GlobalValue to set.
valueThe value to set the ns3::GlobalValue to.
;Multiple \pname{name}=\pname{value} pairs should be delimited by ';'
+ *
+ *
+ * + * Referenced by ns3::GlobalValue::InitializeFromEnv. + */ +const char* NS_GLOBAL_VALUE = "name=value[;...]"; + +/** + * \ingroup core-environ + * \brief Control which logging components are enabled. + * + * Enable logging from specific \pname{component}s, with specified \pname{option}s. + * See the \ref logging module, or the Logging chapter + * in the manual for details on what symbols can be used for specifying + * log level and prefix options. + * + *
+ *
%Parameters
+ *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + *
componentThe logging component to enable.
optionLog level and or prefix to enable. Multiple options should be delimited with '|'
:Multiple logging components can be enabled simultaneously, delimited by ':'
+ *
+ *
+ * + * Referenced by ns3::PrintList, ns3::LogComponent::EnvVarCheck and + * ns3::CheckEnvironmentVariables(), all in \ref log.cc. + */ +const char* NS_LOG = "component=option[|option...][:...]"; + +/** + * \ingroup core-environ + * \brief Where to make temporary directories. + * + * The absolute path where ns-3 should make temporary directories. + * + * See ns3::SystemPath::MakeTemporaryDirectoryName for details on how this environment + * variable is used to create a temporary directory, and how that directory + * will be named. + * + *
+ *
%Parameters
+ *
+ * + * + * + * + * + *
pathThe absolute path in which to create the temporary directory.
+ *
+ *
+ * + * Referenced by ns3::SystemPath::MakeTemporaryDirectoryName. + * + * @{ + */ +const char* TMP = "path"; +const char* TEMP = "path"; +/**@}*/