From 450e4428c7fbda54d363bcb000ae92887380012d Mon Sep 17 00:00:00 2001
From: Henry Weller <http://cfd.direct>
Date: Thu, 29 Oct 2015 22:40:41 +0000
Subject: [PATCH] Make Doxygen documentation consistent with the rest of
OpenFOAM
---
src/OpenFOAM/containers/Lists/UList/UList.H | 90 +++++++++------------
src/OpenFOAM/db/Time/timeSelector.H | 2 +-
src/OpenFOAM/db/error/StaticAssert.H | 15 ++--
src/OpenFOAM/db/error/error.H | 77 +++++++++---------
src/OpenFOAM/db/error/messageStream.H | 73 ++++++-----------
src/OpenFOAM/memory/Xfer/Xfer.H | 68 +++++++---------
6 files changed, 140 insertions(+), 185 deletions(-)
diff --git a/src/OpenFOAM/containers/Lists/UList/UList.H b/src/OpenFOAM/containers/Lists/UList/UList.H
index 0fe01c9015d..1bb858d7969 100644
--- a/src/OpenFOAM/containers/Lists/UList/UList.H
+++ b/src/OpenFOAM/containers/Lists/UList/UList.H
@@ -2,7 +2,7 @@
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
- \\ / A nd | Copyright (C) 2011-2014 OpenFOAM Foundation
+ \\ / A nd | Copyright (C) 2011-2015 OpenFOAM Foundation
\\/ M anipulation |
-------------------------------------------------------------------------------
License
@@ -395,49 +395,40 @@ inline void reverse(UList<T>&);
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-/**
- * \def forAll(list, i)
- * Loop across all elements in \a list
- * \par Usage
- * \code
- * forAll(anyList, i)
- * {
- * statements;
- * }
- * \endcode
- * \sa forAllReverse
-*/
-/**
- * \def forAllReverse(list, i)
- * Reverse loop across all elements in \a list
- * \par Usage
- * \code
- * forAllReverse(anyList, i)
- * {
- * statements;
- * }
- * \endcode
- * \sa forAll
-*/
+//- Loop across all elements in \a list
+// \par Usage
+// \code
+// forAll(anyList, i)
+// {
+// statements;
+// }
+// \endcode
+// \sa forAllReverse
#define forAll(list, i) \
for (Foam::label i=0; i<(list).size(); i++)
+//- Reverse loop across all elements in \a list
+// \par Usage
+// \code
+// forAllReverse(anyList, i)
+// {
+// statements;
+// }
+// \endcode
+// \sa forAll
#define forAllReverse(list, i) \
for (Foam::label i=(list).size()-1; i>=0; i--)
-/**
- * \def forAllIter(Container, container, iter)
- * Iterate across all elements in the \a container object of type
- * \a Container.
- * \par Usage
- * \code
- * forAll(ContainerType, container, iter)
- * {
- * statements;
- * }
- * \endcode
- * \sa forAllConstIter
-*/
+//- Iterate across all elements in the \a container object of type
+// \a Container.
+// \par Usage
+// \code
+// forAll(ContainerType, container, iter)
+// {
+// statements;
+// }
+// \endcode
+// \sa forAllConstIter
#define forAllIter(Container,container,iter) \
for \
( \
@@ -446,19 +437,16 @@ inline void reverse(UList<T>&);
++iter \
)
-/**
- * \def forAllConstIter(Container, container, iter)
- * Iterate across all elements in the \a container object of type
- * \a Container with const access.
- * \par Usage
- * \code
- * forAllConstIter(ContainerType, container, iter)
- * {
- * statements;
- * }
- * \endcode
- * \sa forAllIter
-*/
+//- Iterate across all elements in the \a container object of type
+// \a Container with const access.
+// \par Usage
+// \code
+// forAllConstIter(ContainerType, container, iter)
+// {
+// statements;
+// }
+// \endcode
+// \sa forAllIter
#define forAllConstIter(Container,container,iter) \
for \
( \
diff --git a/src/OpenFOAM/db/Time/timeSelector.H b/src/OpenFOAM/db/Time/timeSelector.H
index 836264f1da7..7074e1267a5 100644
--- a/src/OpenFOAM/db/Time/timeSelector.H
+++ b/src/OpenFOAM/db/Time/timeSelector.H
@@ -162,7 +162,7 @@ public:
//- Return the set of times selected based on the argList options
// including support for \b -newTimes in which times are selected
- // if the file <fName> does not exist in the time directory.
+ // if the file 'fName' does not exist in the time directory.
// Also set the runTime to the first instance or the
// \c constant/ directory if no instances are specified or available
static instantList select
diff --git a/src/OpenFOAM/db/error/StaticAssert.H b/src/OpenFOAM/db/error/StaticAssert.H
index a23aa940775..bfebf929e34 100644
--- a/src/OpenFOAM/db/error/StaticAssert.H
+++ b/src/OpenFOAM/db/error/StaticAssert.H
@@ -2,7 +2,7 @@
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
- \\ / A nd | Copyright (C) 2011 OpenFOAM Foundation
+ \\ / A nd | Copyright (C) 2011-2015 OpenFOAM Foundation
\\/ M anipulation |
-------------------------------------------------------------------------------
License
@@ -62,19 +62,18 @@ class StaticAssertionTest {};
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-// internal use:
+// Internal use:
// ~~~~~~~~~~~~~
-// paste together strings, even if an argument is itself a macro
+
+// Paste together strings, even if an argument is itself a macro
#define StaticAssertMacro(X,Y) StaticAssertMacro1(X,Y)
#define StaticAssertMacro1(X,Y) StaticAssertMacro2(X,Y)
#define StaticAssertMacro2(X,Y) X##Y
-// external use:
+// External use:
// ~~~~~~~~~~~~~
-/**
- * \def StaticAssert(Test)
- * Assert that some test is true at compile-time
-*/
+
+//- Assert that some test is true at compile-time
#define StaticAssert(Test) \
typedef ::Foam::StaticAssertionTest \
< \
diff --git a/src/OpenFOAM/db/error/error.H b/src/OpenFOAM/db/error/error.H
index 97a08b175c6..53b8d321765 100644
--- a/src/OpenFOAM/db/error/error.H
+++ b/src/OpenFOAM/db/error/error.H
@@ -2,7 +2,7 @@
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
- \\ / A nd | Copyright (C) 2011-2012 OpenFOAM Foundation
+ \\ / A nd | Copyright (C) 2011-2015 OpenFOAM Foundation
\\/ M anipulation |
-------------------------------------------------------------------------------
License
@@ -310,46 +310,41 @@ extern IOerror FatalIOError;
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
// Convenience macros to add the file name and line number to the function name
-/**
- * \def FatalErrorIn(functionName)
- * Report an error message using Foam::FatalError for functionName in
- * file __FILE__ at line __LINE__
-*/
-#define FatalErrorIn(fn) \
- ::Foam::FatalError((fn), __FILE__, __LINE__)
-
-/**
- * \def FatalIOErrorIn(functionName, ios)
- * Report an error message using Foam::FatalIOError for functionName in
- * file __FILE__ at line __LINE__
- * for a particular IOstream
-*/
-#define FatalIOErrorIn(fn, ios) \
- ::Foam::FatalIOError((fn), __FILE__, __LINE__, (ios))
-
-/**
- * \def SafeFatalIOErrorIn(functionName, ios, msg)
- * Report an error message using Foam::FatalIOError (or cerr if FatalIOError
- * not yet constructed) for functionName in
- * file __FILE__ at line __LINE__
- * for a particular IOstream
-*/
-#define SafeFatalIOErrorIn(fn, ios, msg) \
- ::Foam::IOerror::SafeFatalIOError((fn), __FILE__, __LINE__, (ios), (msg))
-
-/**
- * \def notImplemented(functionName)
- * Issue a FatalErrorIn for the functionName.
- * This is used for functions that are not currently implemented.
- * The functionName is printed and then abort is called.
- *
- * \note
- * This macro can be particularly useful when methods must be defined to
- * complete the interface of a derived class even if they should never be
- * called for this derived class.
-*/
-#define notImplemented(fn) \
- FatalErrorIn(fn) << "Not implemented" << ::Foam::abort(FatalError);
+//- Report an error message using Foam::FatalError
+// for functionName in file __FILE__ at line __LINE__
+#define FatalErrorIn(functionName) \
+ ::Foam::FatalError((functionName), __FILE__, __LINE__)
+
+//- Report an error message using Foam::FatalIOError
+// for functionName in file __FILE__ at line __LINE__
+// for a particular IOstream
+#define FatalIOErrorIn(functionName, ios) \
+ ::Foam::FatalIOError((functionName), __FILE__, __LINE__, (ios))
+
+//- Report an error message using Foam::FatalIOError
+// (or cerr if FatalIOError not yet constructed)
+// for functionName in file __FILE__ at line __LINE__
+// for a particular IOstream
+#define SafeFatalIOErrorIn(functionName, ios, msg) \
+ ::Foam::IOerror::SafeFatalIOError \
+ ((functionName), __FILE__, __LINE__, (ios), (msg))
+
+//- Issue a FatalErrorIn for a function not currently implemented.
+// The functionName is printed and then abort is called.
+//
+// This macro can be particularly useful when methods must be defined to
+// complete the interface of a derived class even if they should never be
+// called for this derived class.
+#define notImplemented(functionName) \
+ FatalErrorIn(functionName) \
+ << "Not implemented" << ::Foam::abort(FatalError);
+
+//- Issue a FatalErrorIn for a function not currently implemented.
+// The compiler generated function name string is printed and then
+// abort is called.
+#define NotImplemented \
+ notImplemented(__PRETTY_FUNCTION__)
+
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
diff --git a/src/OpenFOAM/db/error/messageStream.H b/src/OpenFOAM/db/error/messageStream.H
index f572e642655..3ccbb27dc14 100644
--- a/src/OpenFOAM/db/error/messageStream.H
+++ b/src/OpenFOAM/db/error/messageStream.H
@@ -218,65 +218,44 @@ extern messageStream Info;
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
// Convenience macros to add the file name and line number to the function name
-/**
- * \def SeriousErrorIn(functionName)
- * Report an error message using Foam::SeriousError for functionName in
- * file __FILE__ at line __LINE__
-*/
-#define SeriousErrorIn(fn) \
+//- Report an error message using Foam::SeriousError
+// for functionName in file __FILE__ at line __LINE__
+#define SeriousErrorIn(fn) \
::Foam::SeriousError((fn), __FILE__, __LINE__)
-/**
- * \def SeriousIOErrorIn(functionName, ios)
- * Report an IO error message using Foam::SeriousError for functionName in
- * file __FILE__ at line __LINE__
- * for a particular IOstream
-*/
-#define SeriousIOErrorIn(fn, ios) \
+//- Report an IO error message using Foam::SeriousError
+// for functionName in file __FILE__ at line __LINE__
+// for a particular IOstream
+#define SeriousIOErrorIn(fn, ios) \
::Foam::SeriousError((fn), __FILE__, __LINE__, ios)
-/**
- * \def WarningIn(functionName)
- * Report a warning using Foam::Warning for functionName in
- * file __FILE__ at line __LINE__
-*/
-#define WarningIn(fn) \
+//- Report a warning using Foam::Warning
+// for functionName in file __FILE__ at line __LINE__
+#define WarningIn(fn) \
::Foam::Warning((fn), __FILE__, __LINE__)
-/**
- * \def IOWarningIn(functionName, ios)
- * Report an IO warning using Foam::Warning for functionName in
- * file __FILE__ at line __LINE__
- * for a particular IOstream
-*/
-#define IOWarningIn(fn, ios) \
+//- Report an IO warning using Foam::Warning
+// for functionName in file __FILE__ at line __LINE__
+// for a particular IOstream
+#define IOWarningIn(fn, ios) \
::Foam::Warning((fn), __FILE__, __LINE__, (ios))
-/**
- * \def InfoIn(functionName)
- * Report a information message using Foam::Info for functionName in
- * file __FILE__ at line __LINE__
-*/
-#define InfoIn(fn) \
+//- Report a information message using Foam::Info
+// for functionName in file __FILE__ at line __LINE__
+#define InfoIn(fn) \
::Foam::Info((fn), __FILE__, __LINE__)
-/**
- * \def IOInfoIn(functionName, ios)
- * Report an IO information message using Foam::Info for functionName in
- * file __FILE__ at line __LINE__
- * for a particular IOstream
-*/
-#define IOInfoIn(fn, ios) \
+//- Report an IO information message using Foam::Info
+// for functionName in file __FILE__ at line __LINE__
+// for a particular IOstream
+#define IOInfoIn(fn, ios) \
::Foam::Info((fn), __FILE__, __LINE__, (ios))
-/**
- * \def Debug(variable)
- * Report a variable name and value using Foam::Pout in
- * file __FILE__ at line __LINE__
-*/
-#define Debug(var) \
- ::Foam::Pout<< "["<< __FILE__ << ":" << __LINE__ << "] " \
- << #var " = " << var << ::Foam::endl
+//- Report a variable name and value
+// using Foam::Pout in file __FILE__ at line __LINE__
+#define Debug(var) \
+ ::Foam::Pout<< "["<< __FILE__ << ":" << __LINE__ << "] " \
+ << #var " " << var << ::Foam::endl
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
diff --git a/src/OpenFOAM/memory/Xfer/Xfer.H b/src/OpenFOAM/memory/Xfer/Xfer.H
index f8118efd95a..ecbb8ed823f 100644
--- a/src/OpenFOAM/memory/Xfer/Xfer.H
+++ b/src/OpenFOAM/memory/Xfer/Xfer.H
@@ -2,7 +2,7 @@
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
- \\ / A nd | Copyright (C) 2011 OpenFOAM Foundation
+ \\ / A nd | Copyright (C) 2011-2015 OpenFOAM Foundation
\\/ M anipulation |
-------------------------------------------------------------------------------
License
@@ -90,6 +90,7 @@ class Xfer
//- Pointer to underlying datatype
mutable T* ptr_;
+
public:
// Constructors
@@ -107,14 +108,17 @@ public:
//- Construct by transferring the contents
inline Xfer(const Xfer<T>&);
+
//- Destructor
inline ~Xfer();
+
// Member Functions
//- Return a null object reference
inline static const Xfer<T>& null();
+
// Member Operators
//- Transfer the contents into the object
@@ -128,67 +132,57 @@ public:
//- Pointer to the underlying datatype
inline T* operator->() const;
-
};
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-/**
- * Construct by copying the contents of the \a arg
- *
- * \sa xferCopyTo, xferMove, xferMoveTo, xferTmp and Foam::Xfer
-*/
+//- Construct by copying the contents of the \a arg
+//
+// \sa xferCopyTo, xferMove, xferMoveTo, xferTmp and Foam::Xfer
template<class T>
inline Xfer<T> xferCopy(const T&);
-/**
- * Construct by transferring the contents of the \a arg
- *
- * \sa xferCopy, xferCopyTo, xferMoveTo, xferTmp and Foam::Xfer
-*/
+//- Construct by transferring the contents of the \a arg
+//
+// \sa xferCopy, xferCopyTo, xferMoveTo, xferTmp and Foam::Xfer
template<class T>
inline Xfer<T> xferMove(T&);
-/**
- * Construct by transferring the contents of the \a arg
- *
- * \sa xferCopy, xferCopyTo, xferMove, xferMoveTo and Foam::Xfer
-*/
+//- Construct by transferring the contents of the \a arg
+//
+// \sa xferCopy, xferCopyTo, xferMove, xferMoveTo and Foam::Xfer
template<class T>
inline Xfer<T> xferTmp(Foam::tmp<T>&);
-/**
- * Construct by copying the contents of the \a arg
- * between dissimilar types
- *
- * \sa xferCopy, xferMove, xferMoveTo, xferTmp and Foam::Xfer
-*/
+//- Construct by copying the contents of the \a arg
+// between dissimilar types
+//
+// \sa xferCopy, xferMove, xferMoveTo, xferTmp and Foam::Xfer
template<class To, class From>
inline Xfer<To> xferCopyTo(const From&);
-/**
- * Construct by transferring the contents of the \a arg
- * between dissimilar types
- *
- * \par Example Use
- * \code
- * DynamicList<label> dynLst;
- * ...
- * labelList plainLst( xferMoveTo<labelList>(dynLst) );
- * \endcode
- *
- * \sa xferCopy, xferCopyTo, xferMove, xferTmp and Foam::Xfer
-*/
+//- Construct by transferring the contents of the \a arg
+// between dissimilar types
+//
+// \par Example Use
+// \code
+// DynamicList<label> dynLst;
+// ...
+// labelList plainLst( xferMoveTo<labelList>(dynLst) );
+// \endcode
+//
+// \sa xferCopy, xferCopyTo, xferMove, xferTmp and Foam::Xfer
template<class To, class From>
inline Xfer<To> xferMoveTo(From&);
-} // End namespace Foam
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+} // End namespace Foam
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
--
GitLab