diff --git a/bin/tools/doxyFilter.awk b/bin/tools/doxyFilter.awk index 0a581a61a1..a096684722 100644 --- a/bin/tools/doxyFilter.awk +++ b/bin/tools/doxyFilter.awk @@ -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 diff --git a/src/OpenFOAM/containers/HashTables/HashPtrTable/HashPtrTable.H b/src/OpenFOAM/containers/HashTables/HashPtrTable/HashPtrTable.H index daf19328d0..548066d19f 100644 --- a/src/OpenFOAM/containers/HashTables/HashPtrTable/HashPtrTable.H +++ b/src/OpenFOAM/containers/HashTables/HashPtrTable/HashPtrTable.H @@ -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); diff --git a/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H b/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H index f20e905920..5c467a2562 100644 --- a/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H +++ b/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H @@ -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. diff --git a/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H b/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H index a496b6b630..926a3f9016 100644 --- a/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H +++ b/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H @@ -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 class Iterator; - //- Friendship with the base iterator is required. + //- An iterator with const access to HashTable internals. friend class Iterator; + + //- An iterator with non-const access to HashTable internals. friend class Iterator; @@ -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 toc() const; - //- Return the table of contents as a sorted list + //- The table of contents (the keys) in sorted order List sortedToc() const; - //- Return table of contents sorted using the specified comparator + //- The table of contents (the keys) sorted according to the + //- specified comparator template List 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 List 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 List 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 List 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 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 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 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&& 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& rhs) const; - //- The opposite of the equality operation. Takes linear time. + //- The opposite of the equality operation. bool operator!=(const HashTable& 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; diff --git a/src/OpenFOAM/containers/HashTables/Map/Map.H b/src/OpenFOAM/containers/HashTables/Map/Map.H index 784a123a74..f6910a73cd 100644 --- a/src/OpenFOAM/containers/HashTables/Map/Map.H +++ b/src/OpenFOAM/containers/HashTables/Map/Map.H @@ -48,7 +48,7 @@ namespace Foam { /*---------------------------------------------------------------------------*\ - Class Map Declaration + Class Map Declaration \*---------------------------------------------------------------------------*/ template @@ -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) diff --git a/src/OpenFOAM/containers/HashTables/PtrMap/PtrMap.H b/src/OpenFOAM/containers/HashTables/PtrMap/PtrMap.H index 4e86e1aae9..915edf49ad 100644 --- a/src/OpenFOAM/containers/HashTables/PtrMap/PtrMap.H +++ b/src/OpenFOAM/containers/HashTables/PtrMap/PtrMap.H @@ -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) diff --git a/src/OpenFOAM/containers/Lists/FixedList/FixedList.H b/src/OpenFOAM/containers/Lists/FixedList/FixedList.H index af54d5c782..ecac3b5779 100644 --- a/src/OpenFOAM/containers/Lists/FixedList/FixedList.H +++ b/src/OpenFOAM/containers/Lists/FixedList/FixedList.H @@ -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; diff --git a/src/OpenFOAM/containers/Lists/PackedList/PackedList.H b/src/OpenFOAM/containers/Lists/PackedList/PackedList.H index ee03e4ad27..842a1a100a 100644 --- a/src/OpenFOAM/containers/Lists/PackedList/PackedList.H +++ b/src/OpenFOAM/containers/Lists/PackedList/PackedList.H @@ -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. // diff --git a/src/OpenFOAM/containers/Lists/UIndirectList/UIndirectList.H b/src/OpenFOAM/containers/Lists/UIndirectList/UIndirectList.H index 61ddf3bed9..eac9eaf415 100644 --- a/src/OpenFOAM/containers/Lists/UIndirectList/UIndirectList.H +++ b/src/OpenFOAM/containers/Lists/UIndirectList/UIndirectList.H @@ -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; diff --git a/src/OpenFOAM/containers/Lists/UList/UList.H b/src/OpenFOAM/containers/Lists/UList/UList.H index b33f170689..83ee18a855 100644 --- a/src/OpenFOAM/containers/Lists/UList/UList.H +++ b/src/OpenFOAM/containers/Lists/UList/UList.H @@ -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