0031363: Documentation - broken Doxygen documentation of header files in Standard package

Documentation is corrected

src/Standard/Standard_CString.hxx

@@ -12,7 +12,8 @@
 // Alternatively, this file may be used under the terms of Open CASCADE
 // commercial license or contractual agreement.
 
-//!@file Functions working with plain C strings
+//!@file
+//! Functions working with plain C strings
 
 #ifndef _Standard_CString_HeaderFile
 # define _Standard_CString_HeaderFile

src/Standard/Standard_Dump.hxx

@@ -19,7 +19,9 @@
 #include <Standard_SStream.hxx>
 #include <TCollection_AsciiString.hxx>
 
+//!@file
 //! The file contains interface to prepare dump output for OCCT objects. Format of the dump is JSON.
+//!
 //! To prepare this output, implement method DumpJson in the object and use macro functions from this file.
 //! Macros have one parameter for both, key and the value. It is a field of the current class. Macro has internal analyzer that
 //! uses the variable name to generate key. If the parameter has prefix symbols "&", "*" and "my", it is cut.
@@ -240,7 +242,7 @@ public:
   //! Returns length value for enum type
   Standard_EXPORT static Standard_Integer JsonKeyLength (const Standard_JsonKey theKey);
 
-  //! @param theStream source value
+  //! @param theOStream source value
   static Standard_EXPORT void AddValuesSeparator (Standard_OStream& theOStream);
 
   //! Returns default prefix added for each pointer info string if short presentation of pointer used
@@ -281,7 +283,6 @@ public:
   //! Convert field name into dump text value, removes "&" and "my" prefixes
   //! An example, for field myValue, theName is Value, for &myCLass, the name is Class
   //! @param theField a source value 
-  //! @param theName [out] an updated name 
   Standard_EXPORT static TCollection_AsciiString DumpFieldToName (const TCollection_AsciiString& theField);
 
 private:

src/Standard/Standard_Failure.hxx

@@ -54,14 +54,10 @@ public:
   //! Destructor
   Standard_EXPORT ~Standard_Failure();
 
-  //! Prints on the stream <s> the exception name followed by
-  //! the error message.
-  //! Level: Advanced
-  //! Warning:
-  //! The operator "OStream& operator<< (Standard_OStream&,
-  //! Handle(Standard_Failure)&)"
-  //! is implemented. (This operator uses the method Print)
-  Standard_EXPORT void Print (Standard_OStream& s) const;
+  //! Prints on the stream @p theStream the exception name followed by the error message.
+  //!
+  //! Note: there is a short-cut @c operator<< (Standard_OStream&, Handle(Standard_Failure)&)
+  Standard_EXPORT void Print (Standard_OStream& theStream) const;
   
   //! Returns error message
   Standard_EXPORT virtual Standard_CString GetMessageString() const;

src/Standard/Standard_Handle.hxx

@@ -407,8 +407,7 @@ namespace opencascade {
 #define Handle(Class) opencascade::handle<Class>
 
 //! Computes a hash code for the standard handle, in the range [1, theUpperBound]
-//! @param TheTransientType the type of the object the handle is referred to
-//! @param theHandle the standard handle which hash code is to be computed
+//! @param theHandle the handle which hash code is to be computed
 //! @param theUpperBound the upper bound of the range a computing hash code must be within
 //! @return a computed hash code, in the range [1, theUpperBound]
 template <class TheTransientType>

src/Standard/Standard_Mutex.hxx

@@ -24,7 +24,6 @@
   #include <windows.h>
 #else
   #include <pthread.h>
-  ///#include <sys/errno.h>
   #include <unistd.h>
   #include <time.h>
 #endif

src/Standard/Standard_ReadLineBuffer.hxx

@@ -53,6 +53,7 @@ public:
   //! @return pointer to the line or NULL on error / end of reading buffer
   //!         (in case of NULL result theStream should be checked externally to identify the presence of errors).
   //!          Empty lines will be returned also with zero length.
+  //! @param theStream [inout] - the stream to read from.
   //! @param theLineLength [out] - output parameter defined length of returned line.
   template<typename Stream_T>
   const char* ReadLine (Stream_T& theStream,
@@ -66,6 +67,7 @@ public:
   //! @return pointer to the line or NULL on error / end of reading buffer
   //!         (in case of NULL result theStream should be checked externally to identify the presence of errors).
   //!          Empty lines will be returned also with zero length.
+  //! @param theStream [inout] - the stream to read from.
   //! @param theLineLength [out] - output parameter defined length of returned line.
   //! @param theReadData   [out] - output parameter defined the number of elements successfully read from the stream during this call,
   //!                              it can be zero if no data was read and the line is taken from the buffer.

src/Standard/Standard_WarningsDisable.hxx

@@ -11,7 +11,8 @@
 // Alternatively, this file may be used under the terms of Open CASCADE
 // commercial license or contractual agreement.
 
-//!@file Supresses compiler warnings.
+//!@file
+//! Supresses compiler warnings.
 //!
 //! Standard_WarningsDisable.hxx disables all compiler warnings.
 //! Standard_WarningsRestore.hxx restore the previous state of warnings.
@@ -20,9 +21,11 @@
 //! header files to avoid compiler warnings to be generated for these files.
 //! They should always be used in pair:
 //!
+//! @code
 //! #include <Standard_WarningsDisable.hxx>
 //! #include <dirty_header.h> // some header that can generate warnings
 //! #include <Standard_WarningsRestore.hxx>
+//! @endcode
 
 #if defined(__clang__)
   #pragma clang diagnostic push

src/Standard/Standard_WarningsRestore.hxx

@@ -11,7 +11,8 @@
 // Alternatively, this file may be used under the terms of Open CASCADE
 // commercial license or contractual agreement.
 
-//!@file Restores compiler warnings suppressed by inclusion of Standard_WarningsDisable.hxx.
+//!@file
+//! Restores compiler warnings suppressed by inclusion of Standard_WarningsDisable.hxx.
 //!
 //! Standard_WarningsDisable.hxx disables all compiler warnings.
 //! Standard_WarningsRestore.hxx restore the previous state of warnings.
@@ -20,9 +21,11 @@
 //! header files to avoid compiler warnings to be generated for these files.
 //! They should always be used in pair:
 //!
+//! @code
 //! #include <Standard_WarningsDisable.hxx>
 //! #include <dirty_header.h> // some header that can generate warnings
 //! #include <Standard_WarningsRestore.hxx>
+//! @endcode
 
 #if defined(__clang__)
   #pragma clang diagnostic pop