Небольшие правки документации и коментариев

TODO

@@ -2,16 +2,13 @@
 
 - Внести в проект реализацию протокола PLCNet // нужно ли 
 
-- написать "uniset-check" автоматический тест основных функций 
-(saveState/Value, getState/Value, setState/Value и т.п.)
+- написать "uniset-check" автоматический тест основных функций (getValue/setValue и т.п.)
 
 - сделать, чтобы можно было Debug пускать через syslog (да ещё и на другую машину)
 
 - Подумать и реализовать механизм хранения ссылок (IOR) с использованием разделяемой памяти...
 (сейчас есть IORFile и omniNames). // нужно ли
 
-- Сделать ObjectIndex_ArrayXML. т.е. использовать vector, при этом считывая индексы из XML.  // нужно ли
-
 - (IONotifyController): Разработать механизм заказа переодических уведомлений (msec), независимо от того, менялись ли датчики..
 - (IONotifyController): Разработать механизм заказа группы датчиков сразу (и ответ тоже группой)
 
@@ -27,6 +24,4 @@ codegen:
 Version 2.0
 ============
 - написать документацию по ModbusSlave
-- рефакторинг класса логов (DebugStream)
 - циклическое хранилище для аварийных следов на основе SQLite
-

extensions/DBServer-SQLite/SQLiteInterface.h

@@ -81,7 +81,7 @@ class SQLiteResult;
 // Памятка:
 // Включение режима для журнала - "вести в памяти" (чтобы поберечь CompactFlash)
 // PRAGMA journal_mode = MEMORY
-//
+// При этом конечно есть риск потерять данные при выключении..
 // ----------------------------------------------------------------------------
 class SQLiteInterface
 {

extensions/include/Calibration.h

@@ -7,9 +7,8 @@
 #include <ostream>
 // -----------------------------------------------------------------------------
 /*!
-    Класс позволяющий загружать калибровочные 
-характеристики из конфигурационного файла 
-и получать по ней точки.
+    Класс позволяющий загружать калибровочную
+характеристику из конфигурационного (xml)файла и получать по ней точки.
 \code
 C, калиброванное значение
   ^
@@ -20,6 +19,33 @@ C, калиброванное значение
    -------->
            R(raw value), сырое значение
 \endcode
+
+Сами диаграммы представляют из себя следующую секцию в xml
+x - сырое значение (по которому ведётся поиск)
+y - калиброванное значение
+\code
+<Calibrations name="Calibrations">
+    <diagram name="testcal">
+        <point x="-200" y="-60"/>
+        <point x="-100" y="-60"/>
+        <point x="-50" y="-20"/>
+        <point x="0" y="0"/>
+        <point x="50" y="20"/>
+        <point x="100" y="60"/>
+        <point x="200" y="60"/>
+    </diagram>
+    <diagram name="NNN">
+    ...
+    </diagram>
+    <diagram name="ZZZ">
+    ...
+    </diagram>
+    ...
+</Calibrations>
+\endcode
+
+Диаграмма позволяет задать множество точек. На отрезках между точками используется линейная аппроксимация.
+
 */
 class Calibration
 {

extensions/include/DigitalFilter.h

 //--------------------------------------------------------------------------
-// Цифровой фильтр с двумя (опционально) уровнями фильтрации сигнала
-// Первый уровень фильтра усредняет несколько значений, переданных через массив
-// Второй уровень - математическая реалезация RC фильтра
-// После вызова конструктора фильтра, его необходимо еще проинициализировать
-// вызвав функцию FirstValue
+// Реализация различных цифровых фильтров
 //--------------------------------------------------------------------------
 #ifndef DigitalFilter_H_
 #define DigitalFilter_H_

extensions/include/MTR.h

 // --------------------------------------------------------------------------
-// --------------------------------------------------------------------------
 #ifndef _MTR_H_
 #define _MTR_H_
 // -----------------------------------------------------------------------------

extensions/include/VTypes.h

@@ -17,19 +17,19 @@ namespace VTypes
             vtUnknown,
             vtF2,        /*!< двойное слово float(4 байта). В виде строки задаётся как \b "F2". */
             vtF4,        /*!< 8-х байтовое слово (double). В виде строки задаётся как \b "F4". */
-            vtByte,        /*!< байт.  В виде строки задаётся как \b "byte". */
-            vtUnsigned,    /*!< беззнаковое целое (2 байта).  В виде строки задаётся как \b "unsigned". */
+            vtByte,      /*!< байт.  В виде строки задаётся как \b "byte". */
+            vtUnsigned,  /*!< беззнаковое целое (2 байта).  В виде строки задаётся как \b "unsigned". */
             vtSigned,    /*!< знаковое целое (2 байта). В виде строки задаётся как \b "signed". */
             vtI2,        /*!< целое (4 байта). В виде строки задаётся как \b "I2".*/
-            vtU2        /*!< беззнаковое целое (4 байта). В виде строки задаётся как \b "U2".*/
+            vtU2         /*!< беззнаковое целое (4 байта). В виде строки задаётся как \b "U2".*/
         };
 
         std::ostream& operator<<( std::ostream& os, const VType& vt );
 
         // -------------------------------------------------------------------------
-        std::string type2str( VType t );    /*!< преобразование строки в тип */
+        std::string type2str( VType t );           /*!< преобразование строки в тип */
         VType str2type( const std::string& s );    /*!< преобразование названия в строку */
-        int wsize( VType t );             /*!< длина данных в словах */
+        int wsize( VType t );                      /*!< длина данных в словах */
     // -------------------------------------------------------------------------
     class F2
     {

include/ComPort485F.h

@@ -21,7 +21,7 @@ class ComPort485F:
 {
     public:
 
-        ComPort485F( std::string comDevice, int gpio_num, bool tmit_ctrl=false );
+        ComPort485F( const std::string& comDevice, int gpio_num, bool tmit_ctrl=false );
     
         virtual void sendByte( unsigned char x );
         virtual void setTimeout( int timeout );

include/Configuration.h

@@ -34,14 +34,15 @@
 #include "IORFile.h"
 #include "Debug.h"
 
-class SystemGuard;
 /*
     В функции main нужно вызвать конструктор класса Configuration
-    fileConf - название файла конфигурации, который будет открываться
-    из в каталоге conf того каталога, откуда была запущена программа.
-    getTopDir позволяет получить каталог, откуда запущена программа
-*/
+    fileConf - название файла конфигурации, который будет открываться.
+    Если в каталоге conf того каталога, откуда была запущена программа.
+    getTopDir позволяет получить каталог, откуда запущена программа.
 
+    Современный способ инициализации:
+    UniSetTypes::uniset_init(argc,argv);
+*/
 namespace UniSetTypes
 {
     /*!
@@ -54,10 +55,10 @@ namespace UniSetTypes
     public:
             virtual ~Configuration();
 
-            /*!    конфигурирование xml-файлом ( предпочтительный способ )    */
+            /*! конфигурирование xml-файлом ( предпочтительный способ )    */
             Configuration( int argc, const char* const* argv, const std::string& xmlfile="" );
 
-            /*!    конфигурирование xml-файлом    */
+            /*! конфигурирование xml-файлом    */
             Configuration( int argc, const char* const* argv, ObjectIndex* oind, const std::string& xmlfile="" );
 
             /*! устаревший вариант, для поддержки старых проектов */
@@ -184,8 +185,6 @@ namespace UniSetTypes
         
         std::string getPort( const std::string& port="" );
             
-        friend class ::SystemGuard;
-//        friend bool SystemGuard::pingNode();
         std::string rootDir;
         UniXML unixml;
 

include/IORFile.h

 /* File: This file is part of the UniSet project
- * Copyright (C) 2002 Vitaly Lipatov
+ * Copyright (C) 2002 Vitaly Lipatov, Pavel Vainerman
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

include/Mutex.h

@@ -110,8 +110,8 @@ namespace UniSetTypes
             bool tryrlock();
             bool trywrlock();
 
-               uniset_rwmutex (const uniset_rwmutex& r);
-               const uniset_rwmutex &operator=(const uniset_rwmutex& r);
+            uniset_rwmutex (const uniset_rwmutex& r);
+            const uniset_rwmutex &operator=(const uniset_rwmutex& r);
 
             inline std::string name(){ return nm; }
             inline void setName( const std::string& name ){ nm = name; }

include/NCRestorer.h

@@ -33,7 +33,10 @@
 #include "IONotifyController.h"
 // ------------------------------------------------------------------------------------------
 /*!
-    Это абстрактный интерфейс. В чистом виде не используется.
+	Интерфейс для записи в файл и восстановления из файла списка заказчиков по датчикам для
+	IONotifyController-а (NC).
+
+    \note Это абстрактный интерфейс. В чистом виде не используется.
 */ 
 class NCRestorer
 {
@@ -99,8 +102,9 @@ class NCRestorer
 };
 // ------------------------------------------------------------------------------------------
 /*!
- * \brief Реализация сохранения списка заказчиков в xml(работа с файлом проекта)
- *    Реализует сохранение списка заказчиков в xml-файле (версия для работы с файлом проекта).
+ * \brief Реализация сохранения списка заказчиков в xml.
+	Данный класс работает с глобальным xml-файлом проекта (обычно configure.xml),
+	поэтому НЕ реализаует функции записи (dump)-а.
 */ 
 class NCRestorer_XML:
     public Restorer_XML,
@@ -111,7 +115,7 @@ class NCRestorer_XML:
         /*!
             \param fname - файл. (формата uniset-project)
         */    
-        NCRestorer_XML(const std::string& fname);
+        NCRestorer_XML( const std::string& fname );
 
         /*!
             \param fname - файл. (формата uniset-project)

include/ORepHelpers.h

@@ -28,7 +28,6 @@
 #include <omniORB4/Naming.hh>
 #include <string>
 #include "Exceptions.h"
-
 // -----------------------------------------------------------------------------------------
 /*!
  * \namespace ORepHelpers
@@ -63,4 +62,6 @@ namespace ORepHelpers
     std::string BadSymbolsToStr();
 
 }
+// -----------------------------------------------------------------------------------------
 #endif
+// -----------------------------------------------------------------------------------------

include/ObjectIndex_Array.h

 /* File: This file is part of the UniSet project
- * Copyright (C) 2002 Vitaly Lipatov
+ * Copyright (C) 2002 Vitaly Lipatov, Pavel Vainerman
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by

include/ObjectIndex_XML.h

 /* File: This file is part of the UniSet project
- * Copyright (C) 2002 Vitaly Lipatov
+ * Copyright (C) 2002 Vitaly Lipatov, Pavel Vainerman
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -17,7 +17,7 @@
  */
 // --------------------------------------------------------------------------
 /*! \file
- * \author Vitaly Lipatov
+ * \author Pavel Vainerman
  */
 // -------------------------------------------------------------------------- 
 #ifndef ObjectIndex_XML_H_
@@ -32,11 +32,7 @@
 namespace UniSetTypes
 {
 
-/*!
-    \todo Проверить функции этого класса на повторную входимость
-    \bug При обращении к objectsMap[0].textName срабатывает исключение(видимо какое-то из std). 
-        Требуется дополнительное изучение.
-*/
+/*! \todo Проверить функции этого класса на повторную входимость */
 class ObjectIndex_XML:
     public ObjectIndex
 {

include/ObjectRepository.h

@@ -70,32 +70,28 @@
         /*! Получение ссылки по заданному полному имени (разыменовывание) */
         UniSetTypes::ObjectPtr resolve(const std::string& name, const std::string& NSName="NameService")throw(UniSetTypes::ORepFailed, UniSetTypes::NameNotFound);
 
-        // Функции не со строковыми именами, а с идентификаторами
-//        void setListId( ListObjectId *lst );
-
         /*!  Проверка существования и доступности объекта */
         bool isExist( UniSetTypes::ObjectPtr oref );
         /*!  Проверка существования и доступности объекта */
         bool isExist( const std::string& fullName );
 
-
         /**
          @defgroup ORepServiceGroup Группа сервисных функций Репозитория объектов
          @{
         */
         
          /*! Тип объекта  */
-         enum ObjectType{
-                             ObjectRef,  /*!< ссылка на объект  */
-                            Section        /*!< подсекция     */
-                        };
+         enum ObjectType
+         {
+             ObjectRef,  /*!< ссылка на объект  */
+             Section     /*!< подсекция     */
+         };
 
         //! Получение списка how_many объектов из секции section.
         bool list(const std::string& section, UniSetTypes::ListObjectName *ls, unsigned int how_many=300)throw(UniSetTypes::ORepFailed);
         
         //! Получние списка how_many подсекций из секции in_section.
         bool listSections(const std::string& in_section, UniSetTypes::ListObjectName *ls, unsigned int how_many=300)throw(UniSetTypes::ORepFailed);
-//        bool list_at(unsigned int start_pos, const char* section, ListObjectName *ls, unsigned int how_many=300)throw(ORepFailed);        
         
     // @}
     // end of ORepServiceGroup 

include/Restorer.h

@@ -18,7 +18,7 @@
  */
 // --------------------------------------------------------------------------
 /*! \file
- * \brief Интерфейс к объекту сохраняющему список заказчиков и сообщений для InfoServer-а
+ * \brief Интерфейс к объекту сохраняющему список заказчиков в файл и умеющему его потом прочитать
  * \author Pavel Vainerman
  */
 // --------------------------------------------------------------------------
@@ -34,7 +34,6 @@
     Это абстрактный интерфейс. 
     Содержит общие для всех xxx_XML интерфейсов функции.
     Расчитан на работу с файлом формата файла проекта.
-    Все функции для поддержки старого формата имеют префикс old_xxx
 */ 
 class Restorer_XML
 {
@@ -98,15 +97,6 @@ class Restorer_XML
         bool getConsumerInfo( UniXML_iterator& it, 
                                 UniSetTypes::ObjectId& cid, UniSetTypes::ObjectId& cnode );
 
-        /*! универсальная функция получения информации о заказчике (id и node)
-            по старому формату файла (<consumer name="/Root/Section/Name" node="xxxx" />)
-            \return true - если идентификаторы определены
-        */
-        bool old_getConsumerInfo( UniXML_iterator& it, 
-                                UniSetTypes::ObjectId& cid, UniSetTypes::ObjectId& cnode );
-
-
-
         /*! Функция поиска по текущему уровню (без рекурсии для дочерних узлов) */
         static xmlNode* find_node( UniXML& xml, xmlNode* root, const std::string& nodename, const std::string& nm="" );
 

include/SMonitor.h

 #ifndef SMonitor_H_
 #define SMonitor_H_
-// ------------------------------------------------------------------------------------------
-#include <string>
+// -----------------------------------------------------------------------------
 #include <list>
 #include <UniSetObject_LT.h>
 #include "UniSetTypes.h"
-// ------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 class SMonitor: 
     public UniSetObject_LT
 {
@@ -28,5 +27,6 @@ class SMonitor:
         MyIDList lst;
         std::string script;
 };
-
+// -----------------------------------------------------------------------------
 #endif
+// -----------------------------------------------------------------------------

include/ThreadCreator.h

@@ -18,7 +18,7 @@
  */
 //----------------------------------------------------------------------------------------
 /*! \file
- * \brief Создатель потоков
+ * \brief Шаблон дла легкого создания потоков (на основе callback).
  * \author Pavel Vainerman
  */
 //--------------------------------------------------------------------------------

include/Trigger.h

@@ -19,7 +19,7 @@
 // --------------------------------------------------------------------------
 /*! \file
  *  \brief Триггер, позволяющий красиво засекать изменения во флаге
- *     \author Vitaly Lipatov
+ *  \author Vitaly Lipatov
 */
 //--------------------------------------------------------------------------
 #ifndef UNITRIGGER_H_

include/TriggerAND.h

@@ -52,19 +52,22 @@
     ...
     MyClass rec;
     // Создание
-    TriggerAND<MyClass, int> tr_and(&rec, &MyClass::out);
+    TriggerAND<MyClass, int> tr(&rec, &MyClass::out);
     
-    // Добавление 'входов'
-    tr_and.add(1,false);
-    tr_and.add(2,true);
-    tr_and.add(3,true);
-    tr_and.add(4,true);
+    // Добавление 'входов' (формирование списка входов)
+    tr.add(1,false);
+    tr.add(2,true);
+    tr.add(3,true);
+    tr.add(4,true);
     ...
-    // Использование
-    // подаёт на вход N1 "1"
+
+    // Использование:
+    // подаём на вход N1 единицу
     // после чего, при изменении состояния 'выхода' будет вызвана функция MyClass::out, в которой производится 
     // фактическая обработка 'изменения состояния'
-    tr_and.commit(1,true);
+
+    tr.commit(1,true);
+
     \endcode
 
 */

include/TriggerOR.h

@@ -52,19 +52,22 @@
     ...
     MyClass rec;
     // Создание
-    TriggerOR<MyClass, int> tr_or(&rec, &MyClass::out);
+    TriggerOR<MyClass, int> tr(&rec, &MyClass::out);
     
     // Добавление 'входов'
-    tr_or.add(1,true);
-    tr_or.add(2,false);
-    tr_or.add(3,false);
-    tr_or.add(4,false);
+    tr.add(1,true);
+    tr.add(2,false);
+    tr.add(3,false);
+    tr.add(4,false);
     ...
-    // Использование
-    // подаёт на вход N1 "0"
+
+    // Использование:
+    // подаём на вход N1 "0"
     // после чего, при изменении состояния 'выхода' будет вызвана функция MyClass::out, в которой производится 
     // фактическая обработка 'изменения состояния'
-    tr_or.commit(1,false);
+
+    tr.commit(1,false);
+
     \endcode
 */
 template<class Caller, typename InputType>

include/TriggerOutput.h

@@ -59,19 +59,26 @@
 
     ...
     MyClass rec;
-    // Создание
+    // Создание:
     TriggerOutput<MyClass,int,int> tr_out(&rec, &MyClass::out);
+
     // формируем OUT триггер с двумя 'выходами'
-    TriggerOutput<MyClass,int,int> tr_out(&rec, &MyClass::out);
     tr_out.add(1,0);
     tr_out.add(2,0);
 
     ...
-    // Использование
+    // Использование:
     // подаём сперва на первый 'выход' значение, второй должен стать в "0",
     // потом на другой...
+
     tr_out.set(1,4);
+
+    cout << ( tr_out.getState(2) !=0 ? "FAIL" : "OK" ) << endl;
+
     tr_out.set(2,3);
+
+    cout << ( tr_out.getState(1) !=0 ? "FAIL" : "OK" ) << endl;
+
     \endcode
 */
 template<class Caller, typename OutIdType, typename ValueType>

src/Communications/ComPort485F.cc

@@ -21,7 +21,7 @@ using namespace std;
 // --------------------------------------------------------------------------------
 /* This is for RTS control (through GPIO) */
 #define GPIO_BA 0xF000
-static void gpio_low_out_en(char gpio_num)
+static void gpio_low_out_en( char gpio_num )
 {
     unsigned long val;
 
@@ -31,7 +31,7 @@ static void gpio_low_out_en(char gpio_num)
     outl(val, GPIO_BA + 4);
 }
 // --------------------------------------------------------------------------------
-static void gpio_low_set_value(char gpio_num, char value)
+static void gpio_low_set_value( char gpio_num, char value )
 {
     unsigned long val;
 
@@ -59,7 +59,7 @@ static void setRTS(int fd, int state)
     ioctl(fd, TIOCMSET, &status);
 }
 // --------------------------------------------------------------------------------
-ComPort485F::ComPort485F( string dev, int gpio_num, bool tmit_ctrl ):
+ComPort485F::ComPort485F( const string& dev, int gpio_num, bool tmit_ctrl ):
     ComPort(dev,false),
     gpio_num(gpio_num),
     tmit_ctrl_on(tmit_ctrl)
@@ -73,7 +73,7 @@ ComPort485F::ComPort485F( string dev, int gpio_num, bool tmit_ctrl ):
     }
 }
 // --------------------------------------------------------------------------------
-void ComPort485F::setTimeout(int timeout)
+void ComPort485F::setTimeout( int timeout )
 {
     tout_msec = timeout / 1000;
     ComPort::setTimeout(timeout);

src/Various/Restorer_XML.cc

@@ -125,55 +125,6 @@ bool Restorer_XML::getConsumerInfo( UniXML_iterator& it,
     return true;
 }
 // -----------------------------------------------------------------------------
-bool Restorer_XML::old_getConsumerInfo( UniXML_iterator& it, 
-                                            ObjectId& cid, ObjectId& cnode )
-{
-    string cname(it.getProp("name"));
-    if( cname.empty() )
-    {
-        if( ulog.is_warn() )
-            ulog.warn() << "(Restorer_XML:old_getConsumerInfo): не указано имя заказчика... пропускаем..." << endl;
-        
-        return false;
-    }
-        
-    cid = conf->oind->getIdByName(cname);
-    if( cid == UniSetTypes::DefaultObjectId )
-    {
-        if( ulog.is_crit() )
-            ulog.crit() << "(Restorer_XML:old_getConsumerInfo): НЕ НАЙДЕН ИДЕНТИФИКАТОР заказчика -->" 
-                            << cname << endl;
-        return false;
-    }
-        
-    string cnodename(it.getProp("node"));
-    if( !cnodename.empty() )
-    {
-        string virtnode = conf->oind->getVirtualNodeName(cnodename);
-        if( virtnode.empty() )
-            cnodename = conf->oind->mkFullNodeName(cnodename,cnodename);
-
-        cnode = conf->oind->getIdByName(cnodename);
-    }
-    else
-        cnode = conf->getLocalNode();
-
-    if( cnode == UniSetTypes::DefaultObjectId )
-    {
-        if( ulog.is_crit() )
-            ulog.crit() << "(Restorer_XML:old_getConsumerInfo): НЕ НАЙДЕН ИДЕНТИФИКАТОР узла -->" 
-                            << cnodename << endl;
-        return false;
-    }
-
-    if( ulog.is_info() )
-    {
-        ulog.info() << "(Restorer_XML:old_getConsumerInfo): " 
-                            << cname << ":" << cnodename << endl;
-    }
-    return true;
-}                                
-// -----------------------------------------------------------------------------
 bool Restorer_XML::check_list_item( UniXML_iterator& it )
 {
     return UniSetTypes::check_filter(it,i_filterField,i_filterValue);