STYLE: more consistent formatting for deprecated items

- Start brief descriptions with 'Deprecated(YYYY-MM)' so that it is
  readily visible in the short method description. Consistent date
  format (YYYY-MM), placed immediately after the \deprecated tag.
This commit is contained in:
Mark Olesen
2018-11-11 17:17:33 +01:00
parent 91cfe4c271
commit ffec4c6fa7
27 changed files with 139 additions and 147 deletions

View File

@ -561,8 +561,8 @@ public:
// Housekeeping
//- Identical to toc()
// \deprecated compatibility name for PackedBoolList (APR-2018)
//- \deprecated(2018-04) compatibility name for PackedBoolList
// \deprecated(2018-04) - use toc() method
inline labelList used() const { return toc(); }
};

View File

@ -55,10 +55,10 @@ SourceFiles
namespace Foam
{
//- Return reference to zero-sized list.
//- Deprecated(2018-07) reference to zero-sized list.
// Compare to List::null() which returns null pointer cast as list reference.
//
// \deprecated This cast is disallowed with many modern compilers (JUL-2018)
// \deprecated(2018-07) This cast is disallowed with many modern compilers
template<class T>
static const List<T>& emptyList()
{
@ -376,9 +376,9 @@ List<OutputIntListType> invertManyToMany
// Optionally with an alternative start index, so that (map[i] == i+start)
labelList identity(const label len, label start=0);
//- Linear search to find the first occurence of the given element.
//- Deprecated(2017-10) search for first occurence of the given element.
// \return The index found or return -1 if not found.
// \deprecated prefer UList find/found methods (deprecated Oct 2017)
// \deprecated(2017-10) - use the UList find/found methods
template<class ListType>
label findIndex
(

View File

@ -209,15 +209,14 @@ public:
{}
// Member functions
// Housekeeping
//- Clear the SHA1 calculation
// \deprecated use reset instead (deprecated Jul 2017)
//- Deprecated(2017-07) clear the SHA1 calculation
// \deprecated(2017-07) - use reset() method
void rewind()
{
sha1().clear();
}
};

View File

@ -558,18 +558,19 @@ public:
//- Move assign from string
inline void operator=(string&& str);
//- Transfer word pointer to the token
// \deprecated in favour of using move assign from word
inline void operator=(word* wordPtr);
//- Transfer string pointer to the token
// \deprecated in favour of using move assign from string
inline void operator=(string* stringPtr);
//- Assign compound with reference counting to token
inline void operator=(compound* compoundPtr);
//- Deprecated(2016-05) transfer word pointer to the token
// \deprecated(2017-11) - use move assign from word
inline void operator=(word* wordPtr);
//- Deprecated(2017-11) transfer string pointer to the token
// \deprecated(2017-11) - use move assign from string
inline void operator=(string* stringPtr);
// Equality
inline bool operator==(const token& t) const;

View File

@ -67,7 +67,7 @@ public:
// Constructors
//- Construct a zero time state, using the current time formattin
//- Construct a zero time state, using the current time formatting
TimeState();
@ -109,8 +109,8 @@ public:
//- Return true if this is a write time
inline bool writeTime() const;
//- Return true if this is a write time.
// \deprecated in favour of writeTime() - MAY-2016
//- Deprecated(2016-05) return true if this is a write time.
// \deprecated(2016-05) - use writeTime() method
inline bool outputTime() const { return this->writeTime(); }
};

View File

@ -1103,16 +1103,16 @@ public:
// Housekeeping
//- Find and return an entry data stream (identical to #lookup method).
//- Deprecated(2018-07) find and return an entry data stream
//
// \deprecated use lookup() method instead (JUL-2018)
// \deprecated(2018-07) - use lookup() method
ITstream& operator[](const word& keyword) const
{
return lookup(keyword);
}
//- Find and return a T.
// \deprecated - same as the get() method (OCT-2018)
//- Deprecated(2018-10) find and return a T.
// \deprecated(2018-10) - use get() method
template<class T>
T lookupType
(
@ -1124,8 +1124,8 @@ public:
return get<T>(keyword, matchOpt(recursive, patternMatch));
}
//- Search dictionary for given keyword.
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
bool found
(
const word& keyword,
@ -1136,10 +1136,8 @@ public:
return found(keyword, matchOpt(recursive, patternMatch));
}
//- Find and return an entry pointer for manipulation if present,
//- or return a nullptr.
//
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
entry* lookupEntryPtr
(
const word& keyword,
@ -1150,8 +1148,8 @@ public:
return findEntry(keyword, matchOpt(recursive, patternMatch));
}
//- Find and return an entry pointer if present, or return a nullptr.
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
const entry* lookupEntryPtr
(
const word& keyword,
@ -1162,12 +1160,8 @@ public:
return findEntry(keyword, matchOpt(recursive, patternMatch));
}
//- Find and return an entry pointer if present, or return a nullptr.
// Allows scoping using '.'.
// Special handling for an absolute anchor (^) at start of the keyword
// and for '..' to ascend into the parent dictionaries.
//
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
const entry* lookupScopedEntryPtr
(
const word& keyword,
@ -1178,27 +1172,30 @@ public:
return findScoped(keyword, matchOpt(recursive, patternMatch));
}
//- Find and return a sub-dictionary pointer if present
//- Deprecated(2018-10)
// Find and return a sub-dictionary pointer if present
// (and a sub-dictionary) otherwise return nullptr.
//
// Search type: non-recursive with patterns.
// \deprecated(2018-10) - use findDict() method
const dictionary* subDictPtr(const word& keyword) const
{
return findDict(keyword, keyType::REGEX);
}
//- Deprecated(2018-10)
//- Find and return a sub-dictionary pointer if present
// (and a sub-dictionary) otherwise return nullptr.
//
// Search type: non-recursive with patterns.
// \deprecated(2018-10) - use findDict() method
dictionary* subDictPtr(const word& keyword)
{
return findDict(keyword, keyType::REGEX);
}
//- Find and return an entry if present, otherwise FatalIOError.
//
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
const entry& lookupEntry
(
const word& keyword,
@ -1209,10 +1206,8 @@ public:
return lookupEntry(keyword, matchOpt(recursive, patternMatch));
}
//- Find and return an entry data stream.
// Default search: non-recursive with patterns.
//
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
ITstream& lookup
(
const word& keyword,
@ -1223,10 +1218,8 @@ public:
return lookup(keyword, matchOpt(recursive, patternMatch));
}
//- Find and return a T, or return the given default value
//- FatalIOError if it is found and there are excess tokens.
//
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
template<class T>
T lookupOrDefault
(
@ -1241,11 +1234,8 @@ public:
(keyword, matchOpt(recursive, patternMatch));
}
//- Find and return a T, or return the given default value
//- and add it to dictionary.
//- FatalIOError if it is found and there are excess tokens.
//
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
template<class T>
T lookupOrAddDefault
(
@ -1260,10 +1250,8 @@ public:
(keyword, deflt, matchOpt(recursive, patternMatch));
}
//- Find an entry if present, and assign to T val.
//- FatalIOError if it is found and there are excess tokens.
//
// \deprecated - use keyType::option version instead (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use keyType::option version
template<class T>
bool readIfPresent
(
@ -1283,7 +1271,7 @@ public:
#undef defineDictionaryGetter
#define defineDictionaryGetter(Func, Type) \
/** Same as get\<Type\> */ \
/** \brief Same as get\<Type\>(const word&, keyType::option) */ \
Type Func \
( \
const word& keyword, \

View File

@ -198,16 +198,16 @@ public:
// Housekeeping
//- Same as findObject
// \deprecated use findObject (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use findObject() method
template<class ObjectType>
const ObjectType* lookupObjectPtr(const word& fieldName) const
{
return this->cfindObject<ObjectType>(fieldName);
}
//- Same as getObjectPtr
// \deprecated use getObjectPtr (OCT-2018)
//- Deprecated(2018-10)
// \deprecated(2018-10) - use getObjectPtr() method
template<class ObjectType>
ObjectType* lookupObjectRefPtr(const word& fieldName) const
{

View File

@ -385,8 +385,8 @@ public:
// Housekeeping
//- Same as findObject
// \deprecated use findObject (OCT-2018)
//- Deprecated(2018-10) find object
// \deprecated(2018-10) - use findObject() method
template<class Type>
const Type* lookupObjectPtr
(
@ -397,9 +397,8 @@ public:
return this->cfindObject<Type>(name, recursive);
}
//- Same as getObjectPtr
//
// \deprecated use getObjectPtr (OCT-2018)
//- Deprecated(2018-10) get object pointer, ignoring constness
// \deprecated(2018-10) - use getObjectPtr() method
template<class Type>
Type* lookupObjectRefPtr
(

View File

@ -536,49 +536,49 @@ public:
#ifdef Foam_argList_1712
//- Read a value from the argument at index.
//- Deprecated(2018-08) read a value from the argument at index.
// Index 1 is the first (non-option) argument.
// \deprecated in favour of get() - AUG-2018
// \deprecated(2018-08) - use get() method
template<class T>
inline T read(const label index) const
{
return this->get<T>(index);
}
//- Read a value from the argument at index.
//- Deprecated(2018-01) read a value from the argument at index.
// Index 1 is the first (non-option) argument.
// \deprecated in favour of read() - JAN-2018
// \deprecated(2018-01) - use get() method
template<class T>
inline T argRead(const label index) const
{
return this->get<T>(index);
}
//- Return true if the named option is found
// \deprecated in favour of found() - JAN-2018
//- Deprecated(2018-01) return true if the named option is found
// \deprecated(2018-01) - use found() method
inline bool optionFound(const word& optName) const
{
return found(optName);
}
//- Return an input stream from the named option
// \deprecated in favour of lookup() - JAN-2018
//- Deprecated(2018-01) return an input stream from the named option
// \deprecated(2018-01) - use lookup() method
inline ITstream optionLookup(const word& optName) const
{
return lookup(optName);
}
//- Read a value from the named option
// \deprecated in favour of opt() - JAN-2018
//- Deprecated(2018-01) read a value from the named option
// \deprecated(2018-01) - use opt() method
template<class T>
inline T optionRead(const word& optName) const
{
return opt<T>(optName);
}
//- Read a value from the named option if present.
//- Deprecated(2018-01) read a value from the named option if present.
// Return true if the named option was found.
// \deprecated in favour of readIfPresent() - JAN-2018
// \deprecated(2018-01) - use readIfPresent() method
template<class T>
inline bool optionReadIfPresent
(
@ -589,10 +589,10 @@ public:
return readIfPresent<T>(optName, val);
}
//- Read a value from the named option if present.
//- Deprecated(2018-01) read a value from the named option if present.
// Return true if the named option was found, otherwise
// use the supplied default and return false.
// \deprecated in favour of readIfPresent() - JAN-2018
// \deprecated(2018-01) - use readIfPresent() method
template<class T>
inline bool optionReadIfPresent
(
@ -604,9 +604,9 @@ public:
return readIfPresent<T>(optName, val, deflt);
}
//- Read a value from the named option if present.
//- Deprecated(2018-01) read a value from the named option if present.
// Return supplied default otherwise.
// \deprecated in favour of lookupOrDefault() - JAN-2018
// \deprecated(2018-01) - use lookupOrDefault() method
template<class T>
inline T optionLookupOrDefault
(
@ -617,8 +617,8 @@ public:
return lookupOrDefault<T>(optName, deflt);
}
//- Read a List of values from the named option
// \deprecated in favour of getList() - JAN-2018
//- Deprecated(2018-01) read a List of values from the named option
// \deprecated(2018-01) - use getList() method
template<class T>
inline List<T> optionReadList(const word& optName) const
{

View File

@ -30,7 +30,7 @@ Description
The wrapped object of type \<T\> must implement a transfer() method and
an operator=() copy method.
\deprecated This class is an artifact from pre-C++11 code (MAR-2018).
\deprecated(2018-03) This class is an artifact from pre-C++11 code.
Note
This class is an artifact from pre-C++11 code, where it was used

View File

@ -259,7 +259,7 @@ public:
// Housekeeping
//- No copy assignment from plain pointer
// \deprecated Convenient, but uncontrolled access (FEB-2018)
// \deprecated(2018-02) Convenient, but uncontrolled access
void operator=(T* p) = delete;
};

View File

@ -30,15 +30,15 @@ namespace Foam
namespace cellModeller
{
//- Equivalent to cellModel::ptr static method.
// \deprecated use cellModel::ptr instead (NOV-2017)
//- Deprecated(2017-11) equivalent to cellModel::ptr static method.
// \deprecated(2017-11) use cellModel::ptr instead
inline const cellModel* lookup(const word& modelName)
{
return cellModel::ptr(modelName);
}
//- Equivalent to cellModel::ptr static method.
// \deprecated use cellModel::ptr instead (NOV-2017)
//- Deprecated(2017-11) equivalent to cellModel::ptr static method.
// \deprecated(2017-11) use cellModel::ptr instead
inline const cellModel* lookup(const label modelIndex)
{
return cellModel::ptr(modelIndex);

View File

@ -198,8 +198,8 @@ public:
//- The unit normal
inline vector unitNormal(const UList<point>& p) const;
//- Legacy name for areaNormal.
// \deprecated Deprecated for new use (JUN-2018)
//- Legacy name for areaNormal()
// \deprecated(2018-06) Deprecated for new use
inline vector normal(const UList<point>& p) const
{
return areaNormal(p); // Legacy definition
@ -450,8 +450,9 @@ struct offsetOp<face>
};
//- Find the longest edge on a face. Face point labels index into pts.
// \deprecated use class method instead (APR-2017)
//- Deprecated(2017-04) find the longest edge on a face.
//- Face point labels index into pts.
// \deprecated(2017-04) use class method instead
label longestEdge(const face& f, const UList<point>& pts);

View File

@ -129,8 +129,8 @@ public:
//- The unit normal
inline vector unitNormal(const UList<point>& points) const;
//- Legacy name for areaNormal.
// \deprecated Deprecated for new use (JUN-2018)
//- Legacy name for areaNormal()
// \deprecated(2018-06) Deprecated for new use
inline vector normal(const UList<point>& points) const
{
return areaNormal(points); // Legacy definition

View File

@ -212,8 +212,8 @@ public:
//- Return unit normal
inline vector unitNormal() const;
//- Legacy name for areaNormal.
// \deprecated Deprecated for new use (JUN-2018)
//- Legacy name for areaNormal().
// \deprecated(2018-06) Deprecated for new use
inline vector normal() const
{
return areaNormal();

View File

@ -206,8 +206,8 @@ public:
// Housekeeping
//- A text representation of the Switch value
// \deprecated - use c_str() instead (MAR-2018)
//- Deprecated(2018-03) text representation of the Switch value
// \deprecated(2018-03) - use c_str() method
inline const char* asText() const { return c_str(); };
};

View File

@ -222,15 +222,15 @@ public:
// Housekeeping
//- Same as two-parameter get()
// \deprecated Use two-parameter get() instead (OCT-2018)
//- Deprecated(2018-10) same as two-parameter get()
// \deprecated(2018-10) - use two-parameter get() method
inline EnumType lookup(const word& key, const dictionary& dict) const
{
return get(key, dict);
}
//- Perform lookupOrDefault with warnings instead of error.
// \deprecated use lookupOrDefault with failsafe option (OCT-2018)
//- Deprecated(2018-10) lookupOrDefault with warnings instead of error.
// \deprecated(2018-10) - use lookupOrDefault() with failsafe option
EnumType lookupOrFailsafe
(
const word& key,

View File

@ -28,8 +28,8 @@ Description
A NamedEnum is a wrapper around a list of names that represent
particular enumeration values.
\deprecated This class is retained for compatibility only and should
not normally be used for any new code.
\deprecated(2017-05) This class is retained for compatibility only and
should be used for any new code.
The Foam::Enum class is robuster, more flexible, easier to use.
See Also

View File

@ -251,9 +251,9 @@ public:
//- Return basename, without extension
inline word nameLessExt() const;
//- Return basename, optionally without extension
// \deprecated in favour of name() or nameLessExt() which describe
// their behaviour more explicitly (MAR-2017).
//- Deprecated(2017-03) return basename, optionally without extension
// \deprecated(2017-03) - use name() or nameLessExt() methods
// which describe their behaviour explicitly
word name(const bool noExt) const
{
return noExt ? this->nameLessExt() : this->name();

View File

@ -356,8 +356,8 @@ struct foundOp
namespace Foam
{
//- Find using C-string as a regex
// \deprecated (FEB-2018) Treating string as regex may be inefficient
//- Deprecated(2018-02) find using C-string as a regex
// \deprecated(2018-02) Treating string as regex may be inefficient
// and lead to unintended results.
// Use regExp, keyType, wordRe instead, or findMatchingStrings()
template<class StringType>
@ -368,8 +368,8 @@ namespace Foam
const bool invert=false
) = delete;
//- Find using string as a regex
// \deprecated (FEB-2018) Treating string as regex may be inefficient
//- Deprecated(2018-02) find using string as a regex
// \deprecated(2018-02) Treating string as regex may be inefficient
// and lead to unintended results.
// Use regExp, keyType, wordRe instead, or findMatchingStrings()
template<class StringType>
@ -380,8 +380,8 @@ namespace Foam
const bool invert=false
) = delete;
//- Subset using C-string as a regex
// \deprecated (FEB-2018) Treating string as regex may be inefficient
//- Deprecated(2018-02) subset using C-string as a regex
// \deprecated(2018-02) Treating string as regex may be inefficient
// and lead to unintended results.
// Use regExp, keyType, wordRe instead, or subsetMatchingStrings()
template<class StringListType>
@ -392,8 +392,8 @@ namespace Foam
const bool invert=false
) = delete;
//- Subset using string as a regex
// \deprecated (FEB-2018) Treating string as regex may be inefficient
//- Deprecated(2018-02) subset using string as a regex
// \deprecated(2018-02) Treating string as regex may be inefficient
// and lead to unintended results.
// Use regExp, keyType, wordRe instead, or subsetMatchingStrings()
template<class StringListType>
@ -404,8 +404,8 @@ namespace Foam
const bool invert=false
) = delete;
//- Subset using C-string as a regex
// \deprecated (FEB-2018) Treating string as regex may be inefficient
//- Deprecated(2018-02) subset using C-string as a regex
// \deprecated(2018-02) Treating string as regex may be inefficient
// and lead to unintended results.
// Use regExp, keyType, wordRe instead, or inplaceSubsetMatchingStrings()
template<class StringListType>
@ -416,8 +416,8 @@ namespace Foam
const bool invert=false
) = delete;
//- Subset using string as a regex
// \deprecated (FEB-2018) Treating string as regex may be inefficient
//- Deprecated(2018-02) subset using string as a regex
// \deprecated(2018-02) Treating string as regex may be inefficient
// and lead to unintended results.
// Use keyType, wordRe instead, or inplaceSubsetMatchingStrings()
template<class StringListType>

View File

@ -99,7 +99,7 @@ public:
LITERAL = 0, //!< String literal
REGEX = 1, //!< Regular expression
ICASE = 2, //!< Ignore case in regular expression
NOCASE = 2, //!< \deprecated Alias for ICASE (deprecated APR-2018)
NOCASE = 2, //!< \deprecated(2018-04) Alias for ICASE
DETECT = 4, //!< Detect if the string contains meta-characters
UNKNOWN = 4, //!< Unknown content.
REGEX_ICASE = (REGEX|ICASE), //!< Combined REGEX and ICASE

View File

@ -410,8 +410,8 @@ public:
// Compatibility
//- Old method name and old parameter ordering.
// \deprecated use setCellSubset instead (JUL-2018)
//- Deprecated(2018-07) old method name and old parameter ordering.
// \deprecated(2018-07) - use setCellSubset() method
inline void setLargeCellSubset
(
const labelUList& region,
@ -433,8 +433,8 @@ public:
}
//- Old method name.
// \deprecated use setCellSubset instead (JUL-2018)
//- Deprecated(2018-07) old method name
// \deprecated(2018-07) - use setCellSubset() method
inline void setLargeCellSubset
(
const labelHashSet& globalCellMap,
@ -449,9 +449,10 @@ public:
}
//- For every exposed face (from getExposedFaces) use supplied
//- (existing!) patch ids
// \deprecated use setCellSubset instead (JUL-2018)
//- Deprecated(2018-07) method
// For every exposed face (from getExposedFaces) use supplied
// (existing!) patch ids
// \deprecated(2018-07) - use setCellSubset() method
inline void setLargeCellSubset
(
const labelList& regions,

View File

@ -81,8 +81,9 @@ public:
//- Extract numbers from things like "-2.358-8" (same as "-2.358e-8")
static scalar readNasScalar(const std::string& str);
//- Extract numbers from things like "-2.358-8" (same as "-2.358e-8")
// \deprecated use readNasScalar instead (deprecated Sep 2017)
//- Deprecated(2017-09)
// Extract numbers from things like "-2.358-8" (same as "-2.358e-8")
// \deprecated(2017-09) - use readNasScalar() method
inline static scalar parseNASCoord(const std::string& str)
{
return readNasScalar(str);

View File

@ -461,8 +461,8 @@ public:
// Housekeeping
//- Compatibility method
// \deprecated use IOobject::selectIO directly (AUG-2018)
//- Deprecated(2018-08) compatibility method
// \deprecated(2018-08) - use IOobject::selectIO directly
static IOobject selectIO
(
const IOobject& io,

View File

@ -89,7 +89,7 @@ public:
NEW, //!< Create a new set and ADD elemets to it
REMOVE, //!< Remove the set (from the file system)
LIST, //!< Print contents of the set
DELETE = SUBTRACT, //!< \deprecated alias for SUBTRACT (OCT-2018)
DELETE = SUBTRACT, //!< \deprecated(2018-10) Alias for SUBTRACT
};
//- The setActions text representations
@ -175,8 +175,8 @@ public:
// Static Functions
//- Convert string to action
// \deprecated use direct access to actionNames (JUL-2018)
//- Deprecated(2018-07) convert string to action
// \deprecated(2018-07) - use actionNames[] directly
static setAction toAction(const word& actionName)
{
return actionNames[actionName];

View File

@ -341,10 +341,6 @@ public:
//- Subtract elements present in set.
virtual void subtractSet(const topoSet& set);
//- Subtract elements present in set.
// \deprecated use subtractSet instead (OCT-2018)
virtual void deleteSet(const topoSet& set);
//- Sync set across coupled patches.
virtual void sync(const polyMesh& mesh);
@ -390,11 +386,17 @@ public:
static void removeFiles(const polyMesh&);
// Member operators
// Member Operators
//- Copy labelHashSet part only
void operator=(const topoSet&);
// Housekeeping
//- Deprecated(2018-10) subtract elements present in set.
// \deprecated(2018-10) - use subtractSet instead
virtual void deleteSet(const topoSet& set);
};

View File

@ -145,8 +145,8 @@ public:
// Housekeeping
//- Compatibility method
// \deprecated use IOobject::selectIO directly (AUG-2018)
//- Deprecated(2018-08) compatibility method
// \deprecated(2018-08) - use IOobject::selectIO directly
static IOobject selectIO
(
const IOobject& io,