From fcd871c0fc2f1e7301c4887c18bf21d0a75b92c9 Mon Sep 17 00:00:00 2001
From: peri4 <peri4ko@yandex.ru>
Date: Sat, 23 Apr 2022 12:32:17 +0300
Subject: [PATCH] doc

---
 libs/main/core/picli.cpp             |   2 +-
 libs/main/core/picout.cpp            |   4 +-
 libs/main/core/pipropertystorage.cpp |   4 +-
 libs/main/system/piprocess.cpp       |   8 ++
 libs/main/system/piprocess.h         | 123 ++++++++++++++++++++++++++-
 5 files changed, 132 insertions(+), 9 deletions(-)

diff --git a/libs/main/core/picli.cpp b/libs/main/core/picli.cpp
index e7d6ecf9..031bd15f 100644
--- a/libs/main/core/picli.cpp
+++ b/libs/main/core/picli.cpp
@@ -66,7 +66,7 @@
 //! a.out --debug -c --value 10
 //! \endcode
 //!
-//! /}
+//! \}
 
 
 PICLI::PICLI(int argc, char * argv[]) {
diff --git a/libs/main/core/picout.cpp b/libs/main/core/picout.cpp
index 138cc1ad..aa2a30fb 100644
--- a/libs/main/core/picout.cpp
+++ b/libs/main/core/picout.cpp
@@ -85,8 +85,8 @@
 //! \~english Class for emit notifications of PICout
 //! \~russian Класс для посылки событий от PICout
 //!
-//! \~english \section PICout_sec0 Synopsis
-//! \~russian \section PICout_sec0 Краткий обзор
+//! \~english \section PICoutNotifier_sec0 Synopsis
+//! \~russian \section PICoutNotifier_sec0 Краткий обзор
 //! \~english
 //! This class used as PICout events emitter. When
 //! PICout constructs with external PIString* buffer
diff --git a/libs/main/core/pipropertystorage.cpp b/libs/main/core/pipropertystorage.cpp
index 152d20cc..fa9fb126 100644
--- a/libs/main/core/pipropertystorage.cpp
+++ b/libs/main/core/pipropertystorage.cpp
@@ -56,8 +56,8 @@
 //! \~russian Элемент PIPropertyStorage
 //!
 //! \~\details
-//! \~english \section PIPropertyStorage_sec0 Synopsis
-//! \~russian \section PIPropertyStorage_sec0 Краткий обзор
+//! \~english \section PIPropertyStorage_sec1 Synopsis
+//! \~russian \section PIPropertyStorage_sec1 Краткий обзор
 //!
 //! \~english
 //! Key-value storage, based on PIVector with PIPropertyStorage::Property elements. Each element in vector
diff --git a/libs/main/system/piprocess.cpp b/libs/main/system/piprocess.cpp
index d0f0aa60..a3e3f23b 100644
--- a/libs/main/system/piprocess.cpp
+++ b/libs/main/system/piprocess.cpp
@@ -40,6 +40,8 @@
 //!
 //! \~\details
 //! \~english
+//! This class able to start external executables, watch for them,
+//! grab output and exit code.
 //!
 //! \~russian
 //!
@@ -47,6 +49,11 @@
 //! \~english \section PIProcess_sec0 Synopsis
 //! \~russian \section PIProcess_sec0 Краткий обзор
 //! \~english
+//! External executable can be started with control or fully independent
+//! from application.\n
+//! Start with control allow you to wait for finish, grab output
+//! and terminate it at any time.\n
+//! You can change working directory and environment of executable.\n
 //!
 //! \~russian
 //!
@@ -55,6 +62,7 @@
 //! \~russian \section PIProcess_sec1 Использование
 //! \~english
 //!
+//!
 //! \~russian
 //!
 //! \}
diff --git a/libs/main/system/piprocess.h b/libs/main/system/piprocess.h
index 3f16f580..16f55225 100644
--- a/libs/main/system/piprocess.h
+++ b/libs/main/system/piprocess.h
@@ -36,34 +36,94 @@ class PIP_EXPORT PIProcess: public PIThread
 {
 	PIOBJECT_SUBCLASS(PIProcess, PIThread)
 public:
+
+	//! \~english Construct empty %PIProcess
+	//! \~russian Создает пустой %PIProcess
 	PIProcess();
+
 	virtual ~PIProcess();
 
+
+	//! \~english Returns last attached execution exit code
+	//! \~russian
 	int exitCode() const {return exit_code;}
+
+	//! \~english Returns current attached execution process ID
+	//! \~russian
 	int pID() const;
 
 	void setGrabInput(bool yes) {g_in = yes;}
+
+	//! \~english Set attached execution grab output stream enabled
+	//! \~russian
 	void setGrabOutput(bool yes) {g_out = yes;}
+
+	//! \~english Set attached execution grab error stream enabled
+	//! \~russian
 	void setGrabError(bool yes) {g_err = yes;}
+
 	void setInputFile(const PIString & path) {f_in.setPath(path);}
+
+	//! \~english Set attached execution grab output stream file
+	//! \~russian
 	void setOutputFile(const PIString & path) {f_out.setPath(path);}
+
+	//! \~english Set attached execution grab error stream file
+	//! \~russian
 	void setErrorFile(const PIString & path) {f_err.setPath(path);}
+
 	void unsetInputFile() {f_in.setPath("");}
+
+	//! \~english Reset attached execution grab output stream file
+	//! \~russian
 	void unsetOutputFile() {f_out.setPath("");}
+
+	//! \~english Reset attached execution grab error stream file
+	//! \~russian
 	void unsetErrorFile() {f_err.setPath("");}
+
+	//! \~english Returns current attached execution working directory or empty string if it wasn`t set
+	//! \~russian
 	PIString workingDirectory() const {return wd;}
+
+	//! \~english Set attached execution working directory
+	//! \~russian
 	void setWorkingDirectory(const PIString & path) {wd = path;}
+
+	//! \~english Rseet attached execution working directory, application working dir will be used
+	//! \~russian
 	void resetWorkingDirectory() {wd.clear();}
+
+	//! \~english Returns all attached execution output stream
+	//! \~russian
 	PIByteArray readOutput() {f_out.open(PIIODevice::ReadOnly); return f_out.readAll();}
+
+	//! \~english Returns all attached execution error stream
+	//! \~russian
 	PIByteArray readError() {f_err.open(PIIODevice::ReadOnly); return f_err.readAll();}
 
+
+	//! \~english Returns current attached execution environment
+	//! \~russian
 	PIStringList environment() {return env;}
+
+	//! \~english Clear current attached execution environment. Call before \a exec()
+	//! \~russian
 	void clearEnvironment() {env.clear();}
+
+	//! \~english Remove variable "variable" from current attached execution environment. Call before \a exec()
+	//! \~russian
 	void removeEnvironmentVariable(const PIString & variable);
+
+	//! \~english Set variable "variable" to "value" in current attached execution environment. Call before \a exec()
+	//! \~russian
 	void setEnvironmentVariable(const PIString & variable, const PIString & value);
 
-	EVENT_HANDLER1(void, exec, const PIString & , program) {args.clear(); args << program; exec_();}
+	//! \~english Start attached execution "program" with one argument "arg"
+	//! \~russian
 	void exec(const PIString & program, const PIString & arg) {args.clear(); args << program << arg; exec_();}
+
+	EVENT_HANDLER1(void, exec, const PIString & , program) {args.clear(); args << program; exec_();}
 	EVENT_HANDLER2(void, exec, const PIString & , program, const PIStringList & , args_) {args.clear(); args << program << args_; exec_();}
 	EVENT_HANDLER(void, terminate);
 	EVENT_HANDLER(bool, waitForFinish) {return waitForFinish(60000);}
@@ -72,14 +132,69 @@ public:
 	EVENT1(execStarted, PIString, program)
 	EVENT2(execFinished, PIString, program, int, exit_code)
 
-	static void execIndependent(const PIString & program) {execIndependent(program, PIStringList());}
-	static void execIndependent(const PIString & program, const PIString & arg) {execIndependent(program, PIStringList() << arg);}
-	static void execIndependent(const PIString & program, const PIStringList & args_);
 
+	//! \~english Start detached execution "program" without arguments
+	//! \~russian
+	static void execIndependent(const PIString & program) {execIndependent(program, PIStringList());}
+
+	//! \~english Start detached execution "program" with one argument "arg"
+	//! \~russian
+	static void execIndependent(const PIString & program, const PIString & arg) {execIndependent(program, PIStringList() << arg);}
+
+	//! \~english Start detached execution "program" with arguments "args"
+	//! \~russian
+	static void execIndependent(const PIString & program, const PIStringList & args);
+
+
+	//! \~english Returns application environment
+	//! \~russian
 	static PIStringList currentEnvironment();
+
+	//! \~english Returns application process ID
+	//! \~russian
 	static int currentPID();
+
+	//! \~english Returns variable "variable" value from application environment
+	//! \~russian
 	static PIString getEnvironmentVariable(const PIString & variable);
 
+//! \handlers
+//! \{
+
+	//! \fn void exec(const PIString & program)
+	//! \~english Start attached execution "program" without arguments
+	//! \~russian
+
+	//! \fn void exec(const PIString & program, const PIStringList & args)
+	//! \~english Start attached execution "program" with arguments "args"
+	//! \~russian
+
+	//! \fn void terminate()
+	//! \~english Immediately terminate attached execution
+	//! \~russian
+
+	//! \fn bool waitForFinish()
+	//! \~english Wait for attached execution finish maximum for 60 seconds
+	//! \~russian
+
+	//! \fn bool waitForFinish(int timeout_msecs)
+	//! \~english Wait for attached execution finish maximum for "timeout_msecs" milliseconds
+	//! \~russian
+
+//! \}
+//! \events
+//! \{
+
+	//! \fn void execStarted(PIString program)
+	//! \~english Raise on attached execution start
+	//! \~russian
+
+	//! \fn void execFinished(PIString program)
+	//! \~english Raise on attached execution finish
+	//! \~russian
+
+//! \}
+
 private:
 	virtual void run();
 	void exec_();