From e8ae1c42a83280a53bae0541a3abaa57d7ed4f80 Mon Sep 17 00:00:00 2001
From: vro <vro@opencascade.com>
Date: Wed, 8 Sep 2021 09:49:52 +0300
Subject: [PATCH] 0032531: Application Framework - There should be methods to
 get explanations of PCDM_StoreStatus and PCDM_ReaderStatus values

Documentation is added for PCDM_ReaderStatus enumeration.

Modified:
- PCDM_ReaderStatus.hxx: each value received a short explanation.
---
 src/PCDM/PCDM_ReaderStatus.hxx | 72 ++++++++++++++++++++++------------
 1 file changed, 48 insertions(+), 24 deletions(-)

diff --git a/src/PCDM/PCDM_ReaderStatus.hxx b/src/PCDM/PCDM_ReaderStatus.hxx
index 5e04801432..1a61abe736 100644
--- a/src/PCDM/PCDM_ReaderStatus.hxx
+++ b/src/PCDM/PCDM_ReaderStatus.hxx
@@ -17,32 +17,56 @@
 #ifndef _PCDM_ReaderStatus_HeaderFile
 #define _PCDM_ReaderStatus_HeaderFile
 
-
+//! Status of reading of a document.
+//! The following values are accessible:
+//! - PCDM_RS_OK: the document was successfully read;
+//! - PCDM_RS_NoDriver: driver is not found for the defined file format;
+//! - PCDM_RS_UnknownFileDriver: check of the file failed (file doesn't exist, for example);
+//! - PCDM_RS_OpenError: attempt to open the file failed;
+//! - PCDM_RS_NoVersion: document version of the file is out of scope;
+//! - PCDM_RS_NoSchema: NOT USED;
+//! - PCDM_RS_NoDocument: document is empty (failed to be read correctly);
+//! - PCDM_RS_ExtensionFailure: NOT USED;
+//! - PCDM_RS_WrongStreamMode: file is not open for reading (a mistaken mode);
+//! - PCDM_RS_FormatFailure: mistake in document data structure;
+//! - PCDM_RS_TypeFailure: data type is unknown;
+//! - PCDM_RS_TypeNotFoundInSchema: data type is not found in schema (STD file format);
+//! - PCDM_RS_UnrecognizedFileFormat: document data structure is wrong (binary file format);
+//! - PCDM_RS_MakeFailure: conversion of data from persistent to transient attributes failed (XML file format);
+//! - PCDM_RS_PermissionDenied: file can't be opened because permission is denied;
+//! - PCDM_RS_DriverFailure: something went wrong (a general mistake of reading of a document);
+//! - PCDM_RS_AlreadyRetrievedAndModified: document is already retrieved and modified in current session;
+//! - PCDM_RS_AlreadyRetrieved: document is already in current session (already retrieved);
+//! - PCDM_RS_UnknownDocument: file doesn't exist on disk;
+//! - PCDM_RS_WrongResource: wrong resource file (.RetrievalPlugin);
+//! - PCDM_RS_ReaderException: no shape section in the document file (binary file format);
+//! - PCDM_RS_NoModel: NOT USED;
+//! - PCDM_RS_UserBreak: user stopped reading of the document;
 enum PCDM_ReaderStatus
 {
-PCDM_RS_OK,
-PCDM_RS_NoDriver,
-PCDM_RS_UnknownFileDriver,
-PCDM_RS_OpenError,
-PCDM_RS_NoVersion,
-PCDM_RS_NoSchema,
-PCDM_RS_NoDocument,
-PCDM_RS_ExtensionFailure,
-PCDM_RS_WrongStreamMode,
-PCDM_RS_FormatFailure,
-PCDM_RS_TypeFailure,
-PCDM_RS_TypeNotFoundInSchema,
-PCDM_RS_UnrecognizedFileFormat,
-PCDM_RS_MakeFailure,
-PCDM_RS_PermissionDenied,
-PCDM_RS_DriverFailure,
-PCDM_RS_AlreadyRetrievedAndModified,
-PCDM_RS_AlreadyRetrieved,
-PCDM_RS_UnknownDocument,
-PCDM_RS_WrongResource,
-PCDM_RS_ReaderException,
-PCDM_RS_NoModel,
-PCDM_RS_UserBreak
+PCDM_RS_OK,                          //!< Success
+PCDM_RS_NoDriver,                    //!< No driver for file format
+PCDM_RS_UnknownFileDriver,           //!< File is bad
+PCDM_RS_OpenError,                   //!< Can't open file
+PCDM_RS_NoVersion,                   //!< Unknown document version
+PCDM_RS_NoSchema,                    //!< NOT USED
+PCDM_RS_NoDocument,                  //!< Document is empty
+PCDM_RS_ExtensionFailure,            //!< NOT USED
+PCDM_RS_WrongStreamMode,             //!< Open mode is mistaken
+PCDM_RS_FormatFailure,               //!< Document data structure is wrong
+PCDM_RS_TypeFailure,                 //!< Data type is unknown
+PCDM_RS_TypeNotFoundInSchema,        //!< Data type is not found in schema
+PCDM_RS_UnrecognizedFileFormat,      //!< Document data structure is wrong
+PCDM_RS_MakeFailure,                 //!< Conversion of data failed
+PCDM_RS_PermissionDenied,            //!< Permission denied to open file
+PCDM_RS_DriverFailure,               //!< General mistake of reading
+PCDM_RS_AlreadyRetrievedAndModified, //!< Document is already retrieved and modified
+PCDM_RS_AlreadyRetrieved,            //!< Document is already retrieved
+PCDM_RS_UnknownDocument,             //!< File doesn't exist
+PCDM_RS_WrongResource,               //!< Wrong resource file
+PCDM_RS_ReaderException,             //!< Wrong data structure
+PCDM_RS_NoModel,                     //!< NOT USED
+PCDM_RS_UserBreak                    //!< User interrupted reading
 };
 
 #endif // _PCDM_ReaderStatus_HeaderFile