Commit ffec4c6f authored by Mark Olesen's avatar Mark Olesen
Browse files

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.
parent 91cfe4c2
......@@ -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(); }
};
......
......@@ -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
(
......
......@@ -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();
}
};
......
......@@ -558,17 +558,18 @@ 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
//- 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);
//- Transfer string pointer to the token
// \deprecated in favour of using move assign from string
//- Deprecated(2017-11) transfer string pointer to the token
// \deprecated(2017-11) - use move assign from string
inline void operator=(string* stringPtr);
//- Assign compound with reference counting to token
inline void operator=(compound* compoundPtr);
// Equality
......
......@@ -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(); }
};
......
......@@ -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, \
......
......@@ -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
{
......
......@@ -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
(
......
......@@ -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
{
......
......@@ -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
......
......@@ -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;
};
......
......@@ -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);
......
......@@ -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);
......
......@@ -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
......
......@@ -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();
......
......@@ -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(); };
};
......
......@@ -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,
......
......@@ -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
......
......@@ -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();
......
......@@ -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.