Skip to content
GitLab
Commit ebd922a3 authored by Mark OLESEN's avatar Mark OLESEN
Browse files

ENH: support longer doxygen brief descriptions.

parent 695716d5
Hide whitespace changes
Inline Side-by-side
bin/tools/doxyFilter.awk
View file @ ebd922a3
......@@ -3,7 +3,7 @@
# \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
# \\ / O peration |
# \\ / A nd | Copyright (C) 2011-2016 OpenFOAM Foundation
# \\/ M anipulation |
# \\/ M anipulation | Copyright (C) 2017 OpenCFD Ltd.
#------------------------------------------------------------------------------
# License
# This file is part of OpenFOAM.
......@@ -29,40 +29,67 @@
#
# Assumes comment strings are formatted as follows
# //- General description
# // more information
# // Detailed information
# // and even more information
# or
# //- General description
# //- that spans several
# //- lines
# // Detailed information
# // and even more information
#
# This should be re-formatted as the following
# //! general description
# /*!
# more information
# /*! \brief General description
# that spans several
# lines
# */
# /*! Detailed information
# and even more information
# */
#
# The intermediate "/*! ... */" block is left-justified to handle
# possible verbatim text
#
#------------------------------------------------------------------------------
# States: 0=normal, 1=brief, 2=details
BEGIN {
state = 0
}
/^ *\/\/-/ {
state = 1
sub(/\/\/-/, "//!")
if (state == 0)
{
# Changed from normal to brief (start of comment block)
printf "/*! \\brief"
state = 1
}
if (state == 1)
{
# Within brief: strip leading
if (!sub(/^ *\/\/- /, ""))
{
sub(/^ *\/\/-/, "")
}
}
print
next
}
/^ *\/\// {
# Start comment block
if (state == 1)
{
# Change from brief to details
printf "*/\n"
printf "/*! "
state = 2
}
# Inside comment block
if (state == 2)
{
# Within details: strip leading
if (!sub(/^ *\/\/ /, ""))
{
sub(/^ *\/\//, "")
......@@ -74,10 +101,10 @@ BEGIN {
}
{
# End comment block
if (state == 2)
# End comment filtering
if (state)
{
printf "*/ "
printf "*/\n"
}
state = 0
print
......
src/OpenFOAM/containers/HashTables/HashPtrTable/HashPtrTable.H
View file @ ebd922a3
......@@ -91,10 +91,10 @@ public:
// Constructors
//- Construct null with default table size
//- Construct null with default table capacity
HashPtrTable();
//- Construct given initial table size
//- Construct given initial table capacity
explicit HashPtrTable(const label size);
//- Construct from Istream using given Istream constructor class
......@@ -123,7 +123,7 @@ public:
// Includes a safeguard against the end-iterator.
T* remove(iterator& iter);
//- Erase an entry specified by given iterator
//- Erase an entry specified by given iterator.
// Includes a safeguard against the end-iterator.
bool erase(iterator& iter);
......
src/OpenFOAM/containers/HashTables/HashSet/HashSet.H
View file @ ebd922a3
......@@ -27,6 +27,7 @@ Class
Description
A HashTable with keys but without contents that is similar to
\c std::unordered_set.
The entries are considered \a unordered since their placement
depends on the method used to generate the hash key index, the
table capacity, insertion order etc. When the key order is
......@@ -121,19 +122,19 @@ public:
// Constructors
//- Construct null with default (128) table size
//- Construct null with default (128) table capacity
HashSet()
:
parent_type()
{}
//- Construct given initial size
//- Construct given initial table capacity
explicit HashSet(const label size)
:
parent_type(size)
{}
//- Construct from Istream with default table size
//- Construct from Istream with default table capacity
HashSet(Istream& is)
:
parent_type(is)
......@@ -183,7 +184,7 @@ public:
// Edit
//- Insert a new entry
//- Insert a new entry, not overwriting existing entries.
// \return True if the entry inserted, which means that it did
// not previously exist in the set.
bool insert(const Key& key)
......@@ -297,7 +298,8 @@ public:
// Writing
//- Write the unordered keys as a list, with line-breaks if list length
// exceeds shortListLen. Using '0' suppresses line-breaks entirely.
//- exceeds shortListLen.
// Using '0' suppresses line-breaks entirely.
Ostream& writeList(Ostream& os, const label shortListLen=0) const
{
return this->writeKeys(os, shortListLen);
......@@ -329,8 +331,8 @@ public:
// Comparison
//- Equality. Two hashset are equal when they have the same keys.
// Independent of table size or order.
//- Sets are equal if all keys are equal,
//- independent of order or underlying storage size.
bool operator==(const this_type& rhs) const;
//- The opposite of the equality operation.
......
src/OpenFOAM/containers/HashTables/HashTable/HashTable.H
View file @ ebd922a3
......@@ -26,6 +26,7 @@ Class
Description
A HashTable similar to \c std::unordered_map.
The entries are considered \a unordered since their placement
depends on the method used to generate the hash key index, the
table capacity, insertion order etc. When the key order is
......@@ -305,8 +306,10 @@ protected:
//- Internally used base for iterator and const_iterator
template<bool Const> class Iterator;
//- Friendship with the base iterator is required.
//- An iterator with const access to HashTable internals.
friend class Iterator<true>;
//- An iterator with non-const access to HashTable internals.
friend class Iterator<false>;
......@@ -325,13 +328,13 @@ public:
// Constructors
//- Construct null with default (128) table size
//- Construct null with default (128) table capacity
HashTable();
//- Construct given initial table size
//- Construct given initial table capacity
explicit HashTable(const label size);
//- Construct from Istream with default table size
//- Construct from Istream with default table capacity
HashTable(Istream& is, const label size = 128);
//- Construct as copy
......@@ -385,18 +388,22 @@ public:
// Table of contents
//- Return the table of contents
//- The table of contents (the keys) in unsorted order.
List<Key> toc() const;
//- Return the table of contents as a sorted list
//- The table of contents (the keys) in sorted order
List<Key> sortedToc() const;
//- Return table of contents sorted using the specified comparator
//- The table of contents (the keys) sorted according to the
//- specified comparator
template<class Compare>
List<Key> sortedToc(const Compare& comp) const;
//- Return the sorted table of contents with keys that satisfy
// the unary predicate, optionally with inverted logic.
//- The table of contents (the keys) selected according to the
//- unary predicate applied to the \b keys.
// \param invert changes the logic to select when the predicate
// is false
// \return sorted list of selected keys
template<class UnaryPredicate>
List<Key> tocKeys
(
......@@ -404,8 +411,11 @@ public:
const bool invert = false
) const;
//- Return the sorted table of contents with values that satisfy
// the unary predicate, optionally with inverted logic.
//- The table of contents (the keys) selected according to the
//- unary predicate applied to the \b values.
// \param invert changes the logic to select when the predicate
// is false
// \return sorted list of selected keys
template<class UnaryPredicate>
List<Key> tocValues
(
......@@ -413,8 +423,11 @@ public:
const bool invert = false
) const;
//- Return the sorted table of contents with keys/values that satisfy
// the binary predicate, optionally with inverted logic.
//- The table of contents (the keys) selected according to the
//- binary predicate applied to the \b keys and \b values.
// \param invert changes the logic to select when the predicate
// is false
// \return sorted list of selected keys
template<class BinaryPredicate>
List<Key> tocEntries
(
......@@ -425,8 +438,9 @@ public:
// Counting
//- Count the number of keys that satisfy the unary predicate,
// optionally with inverted logic.
//- Count the number of keys that satisfy the unary predicate
// \param invert changes the logic to select when the predicate
// is false
template<class UnaryPredicate>
label countKeys
(
......@@ -434,8 +448,9 @@ public:
const bool invert = false
) const;
//- Count the number of values that satisfy the unary predicate,
// optionally with inverted logic.
//- Count the number of values that satisfy the unary predicate
// \param invert changes the logic to select when the predicate
// is false
template<class UnaryPredicate>
label countValues
(
......@@ -443,8 +458,9 @@ public:
const bool invert = false
) const;
//- Count the number of entries that satisfy the binary predicate,
// optionally with inverted logic.
//- Count the number of entries that satisfy the binary predicate.
// \param invert changes the logic to select when the predicate
// is false
template<class BinaryPredicate>
label countEntries
(
......@@ -455,7 +471,7 @@ public:
// Edit
//- Insert a new entry
//- Insert a new entry, not overwriting existing entries.
// \return True if the entry inserted, which means that it did
// not previously exist in the table.
inline bool insert(const Key& key, const T& obj);
......@@ -618,11 +634,11 @@ public:
//- Move assign
void operator=(HashTable<T, Key, Hash>&& rhs);
//- Equality. Hash tables are equal if the keys and values are equal.
// Independent of table storage size and table order.
//- Equality. Tables are equal if all keys and values are equal,
//- independent of order or underlying storage size.
bool operator==(const HashTable<T, Key, Hash>& rhs) const;
//- The opposite of the equality operation. Takes linear time.
//- The opposite of the equality operation.
bool operator!=(const HashTable<T, Key, Hash>& rhs) const;
......@@ -918,7 +934,7 @@ public:
// Iterator access
//- Iterator set to the beginning of the HashTable
//- iterator set to the beginning of the HashTable
inline iterator begin();
//- const_iterator set to the beginning of the HashTable
......@@ -943,7 +959,8 @@ public:
Ostream& printInfo(Ostream& os) const;
//- Write the unordered keys as a list, with line-breaks if list length
// exceeds shortListLen. Using '0' suppresses line-breaks entirely.
//- exceeds shortListLen.
// Using '0' suppresses line-breaks entirely.
Ostream& writeKeys(Ostream& os, const label shortListLen=0) const;
......
src/OpenFOAM/containers/HashTables/Map/Map.H
View file @ ebd922a3
......@@ -48,7 +48,7 @@ namespace Foam
{
/*---------------------------------------------------------------------------*\
Class Map Declaration
Class Map Declaration
\*---------------------------------------------------------------------------*/
template<class T>
......@@ -70,19 +70,19 @@ public:
// Constructors
//- Construct null with default table size
//- Construct null with default table capacity
Map()
:
parent_type()
{}
//- Construct with given table size
//- Construct with given initial table capacity
explicit Map(const label size)
:
parent_type(size)
{}
//- Construct from Istream with default table size
//- Construct from Istream with default table capacity
Map(Istream& is)
:
parent_type(is)
......
src/OpenFOAM/containers/HashTables/PtrMap/PtrMap.H
View file @ ebd922a3
......@@ -62,13 +62,13 @@ public:
// Constructors
//- Construct null with default table size
//- Construct null with default table capacity
PtrMap()
:
parent_type()
{}
//- Construct given initial map size
//- Construct with given initial table capacity
explicit PtrMap(const label size)
:
parent_type(size)
......
src/OpenFOAM/containers/Lists/FixedList/FixedList.H
View file @ ebd922a3
......@@ -129,7 +129,7 @@ public:
//- Construct from value
explicit inline FixedList(const T& val);
//- Construct from C-array
//- Copy construct from C-array
explicit inline FixedList(const T lst[Size]);
//- Copy constructor
......@@ -164,7 +164,7 @@ public:
// Access
//- Return the forward circular index, i.e. next index
// which returns to the first at the end of the list
//- which returns to the first at the end of the list
inline label fcIndex(const label i) const;
//- Return forward circular value (ie, next value in the list)
......@@ -174,7 +174,7 @@ public:
inline T& fcValue(const label i);
//- Return the reverse circular index, i.e. previous index
// which returns to the last at the beginning of the list
//- which returns to the last at the beginning of the list
inline label rcIndex(const label i) const;
//- Return reverse circular value (ie, previous value in the list)
......@@ -184,13 +184,13 @@ public:
inline T& rcValue(const label i);
//- Return a const pointer to the first data element,
// similar to the STL front() method and the string::data() method
//- Return a const pointer to the first data element.
// Similar to the STL front() method and the string::data() method
// This can be used (with caution) when interfacing with C code
inline const T* cdata() const;
//- Return a pointer to the first data element,
// similar to the STL front() method and the string::data() method
//- Return a pointer to the first data element.
// Similar to the STL front() method and the string::data() method
// This can be used (with caution) when interfacing with C code
inline T* data();
......@@ -246,10 +246,10 @@ public:
//- Move element to the last position.
void moveLast(const label i);
//- Swap element with the first element. Fatal on an empty list.
//- Swap element with the first element.
void swapFirst(const label i);
//- Swap element with the last element. Fatal on an empty list.
//- Swap element with the last element.
void swapLast(const label i);
//- Copy (not transfer) the argument contents
......@@ -292,16 +292,14 @@ public:
//- Type of values the FixedList contains
typedef T value_type;
//- Type that can be used for storing into
// FixedList::value_type objects
//- The type used for storing into value_type objects
typedef T& reference;
//- Type that can be used for storing into
// constant FixedList::value_type objects
//- The type used for reading from constant value_type objects.
typedef const T& const_reference;
//- The type that can represent the difference between any two
// FixedList iterator objects
//- FixedList iterator objects
typedef label difference_type;
//- The type that can represent the size of a FixedList
......@@ -486,7 +484,8 @@ public:
void writeEntry(const word& keyword, Ostream& os) const;
//- Write the List, with line-breaks in ASCII if the list length
// exceeds shortListLen. Using '0' suppresses line-breaks entirely.
//- exceeds shortListLen.
// Using '0' suppresses line-breaks entirely.
Ostream& writeList(Ostream& os, const label shortListLen=0) const;
......
src/OpenFOAM/containers/Lists/PackedList/PackedList.H
View file @ ebd922a3
......@@ -268,13 +268,14 @@ public:
// Never auto-vivify entries.
inline unsigned int get(const label i) const;
//- Set value at index I. Return true if value changed.
//- Set value at index I, default value set is the max_value.
// Does auto-vivify for non-existent, non-zero entries.
// Default value set is the max_value.
// \return true if value changed.
inline bool set(const label i, const unsigned int val = ~0u);
//- Unset the entry at index I. Return true if value changed.
//- Unset the entry at index I.
// Never auto-vivify entries.
// \return true if value changed.
inline bool unset(const label i);
//- Return the underlying packed storage
......@@ -287,8 +288,7 @@ public:
//- The list length when packed
inline label packedLength() const;
//- Return the binary size in number of characters
// used in the underlying storage
//- The number of bytes used in the underlying storage
inline std::streamsize byteSize() const;
//- Count number of bits set, O(log(n))
......@@ -366,7 +366,8 @@ public:
Istream& read(Istream& is);
//- Write the List, with line-breaks in ASCII if the list length
// exceeds shortListLen. Using '0' suppresses line-breaks entirely.
//- exceeds shortListLen.
// Using '0' suppresses line-breaks entirely.
// A special indexed output (ASCII only) is triggered by specifying
// a negative value for shortListLen.
//
......
src/OpenFOAM/containers/Lists/UIndirectList/UIndirectList.H
View file @ ebd922a3
......@@ -147,19 +147,17 @@ public:
// STL type definitions
//- Type of values the UList contains.
//- Type of values the list contains.
typedef T value_type;
//- Type that can be used for storing into
// UList::value_type objects.
//- The type used for storing into UList::value_type objects.
typedef T& reference;
//- Type that can be used for storing into
// constant UList::value_type objects
//- The type used for reading from constant UList::value_type objects
typedef const T& const_reference;
//- The type that can represent the difference between any two
// UList iterator objects.
//- UList iterator objects.
typedef label difference_type;
//- The type that can represent the size of a UList.
......@@ -169,8 +167,8 @@ public:
// Writing
//- Write the List, with line-breaks in ASCII if the list length
// exceeds shortListLen. Using '0' suppresses line-breaks entirely.
// Binary output is currently still a bit of an annoyance.
//- exceeds shortListLen.
// Using '0' suppresses line-breaks entirely.
Ostream& writeList(Ostream& os, const label shortListLen=0) const;
......
src/OpenFOAM/containers/Lists/UList/UList.H
View file @ ebd922a3
......@@ -110,11 +110,11 @@ protected:
void writeEntry(Ostream& os) const;
//- Return a validated (start,size) subset range, which means that it
// always addresses a valid section of the list.
//- always addresses a valid section of the list.
labelRange validateRange(const labelRange& range) const;
//- Return a validated (start,size) subset range, which means that it
// always addresses a valid section of the list.
//- always addresses a valid section of the list.
labelRange validateRange
(
std::initializer_list<label> start_size_pair
......@@ -186,7 +186,7 @@ public:
// Access
//- Return the forward circular index, i.e. next index
// which returns to the first at the end of the list
//- which returns to the first at the end of the list
inline label fcIndex(const label i) const;
//- Return forward circular value (ie, next value in the list)
......@@ -196,7 +196,7 @@ public:
inline T& fcValue(const label i);
//- Return the reverse circular index, i.e. previous index
// which returns to the last at the beginning of the list
//- which returns to the last at the beginning of the list
inline label rcIndex(const label i) const;
//- Return reverse circular value (ie, previous value in the list)
......@@ -206,19 +206,19 @@ public:
inline T& rcValue(const label i);
//- Return the binary size in number of characters of the UList
// if the element is a primitive type
//- if the element is a primitive type
// i.e. contiguous<T>() == true.
// Note that is of type streamsize since used in stream ops
std::streamsize byteSize() const;
//- Return a const pointer to the first data element,
// similar to the STL front() method and the string::data() method
//- Return a const pointer to the first data element.
// Similar to the STL front() method and the string::data() method
// This can be used (with caution) when interfacing with C code
inline const T* cdata() const;
//- Return a pointer to the first data element,
// similar to the STL front() method and the string::data() method
//- Return a pointer to the first data element.
// Similar to the STL front() method and the string::data() method
// This can be used (with caution) when interfacing with C code
inline T* data();
......@@ -347,7 +347,7 @@ public:
typedef const T& const_reference;
//- The type that can represent the difference between any two
// UList iterator objects
//- UList iterator objects
typedef label difference_type;
//- The type that can represent the size of a UList
......@@ -539,7 +539,8 @@ public:
void writeEntry(const word& keyword, Ostream& os) const;
//- Write the List, with line-breaks in ASCII if the list length
// exceeds shortListLen. Using '0' suppresses line-breaks entirely.
//- exceeds shortListLen.
// Using '0' suppresses line-breaks entirely.
Ostream& writeList(Ostream& os, const label shortListLen=0) const;