added/updated documentation

src/ebusd/bushandler.h

@@ -487,6 +487,8 @@ class BusHandler : public WaitThread {
   /**
    * Send a scan message on the bus and wait for the answer.
    * @param dstAddress the destination slave address to send to.
+   * @param loadScanConfig true to immediately load the message definitions matching the scan result.
+   * @param reload true to fully reload the scan results.
    * @return the result code.
    */
   result_t scanAndWait(symbol_t dstAddress, bool loadScanConfig = false, bool reload = false);
@@ -538,6 +540,7 @@ class BusHandler : public WaitThread {
   /**
    * Get the next slave address that still needs to be scanned or loaded.
    * @param lastAddress the last returned slave address, or 0 for returning the first one.
+   * @param onlyScanned true to return only already scanned addresses.
    * @return the next slave address that still needs to be scanned or loaded, or @a SYN.
    */
   symbol_t getNextScanAddress(symbol_t lastAddress, bool onlyScanned = false);

src/ebusd/main.cpp

@@ -966,7 +966,8 @@ result_t loadScanConfigFile(MessageMap* messages, symbol_t address, string& rela
     symbol_t checkDest;
     unsigned int checkSw, checkHw;
     map<string, string> defaults;
-    if (!messages->extractDefaultsFromFilename(name.substr(path.length()+1), defaults, &checkDest, &checkSw, &checkHw)) {
+    const string filename = name.substr(path.length()+1);
+    if (!messages->extractDefaultsFromFilename(filename, defaults, &checkDest, &checkSw, &checkHw)) {
       continue;
     }
     if (address != checkDest || (checkSw != UINT_MAX && sw != checkSw) || (checkHw != UINT_MAX && hw != checkHw)) {

src/ebusd/mainloop.cpp

@@ -46,7 +46,7 @@ result_t UserList::getFieldMap(vector<string>& row, string& errorDescription) {
   if (row.empty()) {
     row.push_back("name");
     row.push_back("secret");
-    row.push_back("*level"); // TODO last repeat is repeated as often as necessary in addFromFile...
+    row.push_back("*level");
     return RESULT_OK;
   }
   map<string, string> seen;

src/ebusd/mqtthandler.cpp

@@ -446,7 +446,7 @@ void MqttHandler::notifyTopic(string topic, string data) {
         name = field;
         break;
       case MESSAGEFIELD_DATAFIELDS:
-        //field = field;  // TODO add support for writing a single field
+        // field = field;  // TODO add support for writing a single field
         break;
       default:
         return;
@@ -569,7 +569,7 @@ string MqttHandler::getTopic(Message* message, ssize_t fieldIndex) {
     }
     if (i < m_topicFields.size()) {
       if (m_topicFields[i] == MESSAGEFIELD_DATAFIELDS && fieldIndex >= 0) {
-        ret << message->getFieldName(fieldIndex); // TODO skip ignored fields
+        ret << message->getFieldName(fieldIndex);  // TODO skip ignored fields
       } else {
         message->dumpField(ret, m_topicFields[i]);
       }

src/lib/ebus/data.cpp

@@ -76,7 +76,7 @@ string getDataFieldName(const size_t fieldId) {
     return "comment";
   default:
     return "";
-  };
+  }
 }
 
 result_t DataField::create(vector< map<string, string> >& rows, string& errorDescription,

src/lib/ebus/data.h

@@ -117,8 +117,8 @@ class DataField {
 
   /**
    * Factory method for creating new instances.
-   * @param it the iterator to traverse for the definition parts.
-   * @param end the iterator pointing to the end of the definition parts.
+   * @param rows the mapped field definition rows.
+   * @param errorDescription a string in which to store the error description in case of error.
    * @param templates the @a DataFieldTemplates to be referenced by name, or NULL.
    * @param returnField the variable in which to store the created instance.
    * @param isWriteMessage whether the field is part of a write message (default false).

src/lib/ebus/filereader.cpp

@@ -19,6 +19,8 @@
 #include "lib/ebus/filereader.h"
 #include <sys/stat.h>
 #include <iostream>
+#include <string>
+#include <vector>
 #include <iomanip>
 #include <climits>
 #include <fstream>
@@ -35,7 +37,7 @@ using std::dec;
 
 
 result_t FileReader::readFromFile(const string filename, string& errorDescription, bool verbose,
-    map<string, string>* defaults, size_t* hash, size_t* size, time_t* time) { //TODO use hash etc.
+    map<string, string>* defaults, size_t* hash, size_t* size, time_t* time) {
   struct stat st;
   if (stat(filename.c_str(), &st) != 0) {
     errorDescription = filename;
@@ -132,7 +134,7 @@ bool FileReader::splitFields(istream& ifs, vector<string>& row, unsigned int& li
       *size += length + 1;  // normalized with trailing endl
     }
     if (hash) {
-      *hash ^= (hashFunction(line) << 1) ^ (length << ( 7 * (lineNo % 5)));
+      *hash ^= (hashFunction(line) << 1) ^ (length << (7 * (lineNo % 5)));
     }
     if (!quotedText && (length == 0 || line[0] == '#' || (line.length() > 1 && line[0] == '/' && line[1] == '/'))) {
       if (lineNo == 1) {
@@ -276,11 +278,6 @@ result_t MappedFileReader::addFromFile(vector<string>& row, string& errorDescrip
       subRowsMapped.resize(subRowsMapped.size() - 1);
     }
   }
-/*cout<<"row:"<<MappedFileReader::combineRow(rowMapped);
-for (auto sub : subRowsMapped) {
-  cout<<std::endl<<"  subrow:"<<MappedFileReader::combineRow(sub);
-}
-cout<<std::endl;*/
   if (isDefault) {
     return addDefaultFromFile(rowMapped, subRowsMapped, errorDescription, filename, lineNo);
   }

src/lib/ebus/filereader.h

@@ -21,6 +21,8 @@
 
 #include <algorithm>
 #include <map>
+#include <string>
+#include <vector>
 #include <iomanip>
 #include <mutex>
 #include "lib/ebus/symbol.h"
@@ -92,6 +94,7 @@ class FileReader {
    * @param errorDescription a string in which to store the error description in case of error.
    * @param filename the name of the file being read.
    * @param lineNo the last line number (incremented with each line read).
+   * @param row the definition row to clear and update with the read data (for performance reasons only).
    * @param verbose whether to verbosely log problems.
    * @param hash optional pointer to a @a size_t value for updating with the hash of the line, or NULL.
    * @param size optional pointer to a @a size_t value for updating with the normalized length of the line, or NULL.
@@ -147,13 +150,17 @@ class FileReader {
 };
 
 
+/**
+ * An abstract class derived from @a FileReader that additionally allows to using mapped name/value pairs with one
+ * main map and many sub maps.
+ */
 class MappedFileReader : public FileReader {
  public:
   /**
    * Constructor.
    * @param supportsDefaults whether this instance supports rows with defaults (starting with a star).
    */
-  MappedFileReader(bool supportsDefaults) : FileReader(), m_supportsDefaults(supportsDefaults) {}
+  explicit MappedFileReader(bool supportsDefaults) : FileReader(), m_supportsDefaults(supportsDefaults) {}
 
   /**
    * Destructor.
@@ -170,10 +177,11 @@ class MappedFileReader : public FileReader {
 
   /**
    * Extract default values from the file name.
-   * @param name the name of the file (without path)
+   * @param filename the name of the file (without path)
    * @param defaults the default values by name to add to.
-   * @param software the variable in which to store the numeric software version, or NULL.
-   * @param hardware the variable in which to store the numeric software version, or NULL.
+   * @param destAddress a pointer to a variable in which to store the numeric destination address, or NULL.
+   * @param software a pointer to a in which to store the numeric software version, or NULL.
+   * @param hardware a pointer to a in which to store the numeric hardware version, or NULL.
    * @return true if the minimum parts were extracted, false otherwise.
    */
   virtual bool extractDefaultsFromFilename(string filename, map<string, string>& defaults,
@@ -188,7 +196,7 @@ class MappedFileReader : public FileReader {
   /**
    * Get the field mapping from the given first line.
    * @param row the first line from which to extract the field mapping, or empty to use the default mapping.
-   * @param begin an iterator to the first column of the first line to read (for error reporting).
+   * @param errorDescription a string in which to store the error description in case of error.
    * @return @a RESULT_OK on success, or an error code.
    */
   virtual result_t getFieldMap(vector<string>& row, string& errorDescription) = 0;
@@ -197,7 +205,7 @@ class MappedFileReader : public FileReader {
    * Add a default row that was read from a file.
    * @param row the default row by field name.
    * @param subRows the sub default rows, each by field name.
-   * @param subRowDefaults the sub default values by type and field name to add to.
+   * @param errorDescription a string in which to store the error description in case of error.
    * @param filename the name of the file being read.
    * @param lineNo the current line number in the file being read.
    * @return @a RESULT_OK on success, or an error code.
@@ -212,8 +220,6 @@ class MappedFileReader : public FileReader {
    * Add a definition that was read from a file.
    * @param row the main definition row by field name.
    * @param subRows the sub definition rows, each by field name.
-   * @param rowDefaults all previously extracted default values by type and field name.
-   * @param subRowDefaults all previously extracted sub default values by type and field name.
    * @param errorDescription a string in which to store the error description in case of error.
    * @param filename the name of the file being read.
    * @param lineNo the current line number in the file being read.

src/lib/ebus/message.cpp

@@ -1413,7 +1413,7 @@ result_t Condition::create(const string condName, map<string, string> row, map<s
   } else if (circuit.empty()) {
     circuit = rowDefaults["circuit"];
   }
-  string valueList = row["id"];  // TODO
+  string valueList = row["id"];
   if (valueList.length() == 0) {
     returnValue = new SimpleCondition(condName, condName, circuit, level, name, dstAddress, field);
     return RESULT_OK;
@@ -1801,7 +1801,8 @@ result_t MessageMap::add(Message* message, bool storeByName) {
 }
 
 result_t MessageMap::getFieldMap(vector<string>& row, string& errorDescription) {
-  // type (r[1-9];w;u),circuit,name,[comment],[QQ],ZZ,PBSB,[ID],field1,part (m/s),datatypes/templates,divider/values,unit,comment
+  // type (r[1-9];w;u),circuit,name,[comment],[QQ],ZZ,PBSB,[ID],field1,part (m/s),datatypes/templates,divider/values,
+  //  unit,comment
   // minimum: type,name,PBSB,field,datatype
   if (row.empty()) {
     for (size_t fieldId = MESSAGEFIELD_RANGE_MIN; fieldId <= MESSAGEFIELD_RANGE_MAX; fieldId++) {

src/lib/ebus/message.h

@@ -201,9 +201,11 @@ class Message {
 
   /**
    * Factory method for creating new instances.
-   * @param it the iterator to traverse for the definition parts.
-   * @param end the iterator pointing to the end of the definition parts.
-   * @param defaultsRows a @a vector with rows containing defaults, or NULL.
+   * @param row the mapped message definition row.
+   * @param subRows the mapped field definition rows.
+   * @param rowDefaults the mapped message definition defaults.
+   * @param subRowDefaults the mapped field definition defaults.
+   * @param errorDescription a string in which to store the error description in case of error.
    * @param condition the @a Condition instance for the message, or NULL.
    * @param filename the name of the file being read.
    * @param templates the @a DataFieldTemplates to be referenced by name, or NULL.
@@ -219,9 +221,17 @@ class Message {
   /**
    * Create a new scan @a Message instance.
    * @param broadcast true for broadcast scan message, false for scan message to be sent to a slave address.
+   * @return the new scan @a Message instance.
    */
   static Message* createScanMessage(bool broadcast = false);
 
+  /**
+   * Extract the known field IDs from the input string.
+   * @param str the input string with the field names separated by @a FIELD_SEPARATOR.
+   * @param fields the vector to update with the extracted field IDs with.
+   * @param checkAbbreviated true to also check for abbreviated field names.
+   * @return true when all fields are valid.
+   */
   static bool extractFieldIds(string str, vector<size_t>& fields, bool checkAbbreviated = true);
 
   /**
@@ -837,10 +847,8 @@ class Condition {
   /**
    * Factory method for creating a new instance.
    * @param condName the name of the condition.
-   * @param it the iterator to traverse for the definition parts.
-   * @param end the iterator pointing to the end of the definition parts.
-   * @param defaultDest the valid destination address extracted from the file name (from ZZ part), or empty.
-   * @param defaultCircuit the valid circuit name extracted from the file name (from IDENT part), or empty.
+   * @param row the mapped definition row.
+   * @param rowDefaults the mapped definition defaults.
    * @param returnValue the variable in which to store the created instance.
    * @return @a RESULT_OK on success, or an error code.
    */
@@ -1114,9 +1122,7 @@ class Instruction {
    * @param condition the @a Condition this instruction requires, or null.
    * @param singleton whether this @a Instruction belongs to a set of instructions of which only the first one may be
    * executed for the same source file.
-   * @param defaultDest the default destination address, or empty.
-   * @param defaultCircuit the default circuit name, or empty.
-   * @param defaultSuffix the default circuit name suffix (starting with a "."), or empty.
+   * @param defaults the mapped definition defaults.
    */
   Instruction(Condition* condition, const bool singleton, map<string, string>& defaults)
     : m_condition(condition), m_singleton(singleton), m_defaults(defaults) { }
@@ -1195,10 +1201,7 @@ class LoadInstruction : public Instruction {
    * @param condition the @a Condition this instruction requires, or null.
    * @param singleton whether this @a Instruction belongs to a set of instructions of which only the first one may be
    * executed for the same source file.
-   * @param defaultDest the default destination address (may be overwritten by file name), or empty.
-   * @param defaultCircuit the default circuit name (may be overwritten by file name), or empty.
-   * @param defaultSuffix the default circuit name suffix (starting with a ".", may be overwritten by file name), or
-   * empty.
+   * @param defaults the mapped definition defaults.
    * @param filename the name of the file to load.
    */
   LoadInstruction(Condition* condition, const bool singleton, map<string, string>& defaults, const string filename)
@@ -1293,13 +1296,14 @@ class MessageMap : public MappedFileReader {
   result_t getFieldMap(vector<string>& row, string& errorDescription) override;
 
   // @copydoc
-  virtual result_t addDefaultFromFile(map<string, string>& row, vector< map<string, string> >& subRows,
+  result_t addDefaultFromFile(map<string, string>& row, vector< map<string, string> >& subRows,
       string& errorDescription, const string filename, unsigned int lineNo) override;
 
   /**
    * Read the @a Condition instance(s) from the types field.
    * @param types the field from which to read the @a Condition instance(s).
    * @param filename the name of the file being read.
+   * @param errorDescription a string in which to store the error description in case of error.
    * @param condition the variable in which to store the result.
    * @return @a RESULT_OK on success, or an error code.
    */
@@ -1332,6 +1336,7 @@ class MessageMap : public MappedFileReader {
 
   /**
    * Resolve all @a Condition instances.
+   * @param errorDescription a string in which to store the error description in case of error.
    * @param verbose whether to verbosely add all problems to the error message.
    * @return @a RESULT_OK on success, or an error code.
    */
@@ -1340,6 +1345,7 @@ class MessageMap : public MappedFileReader {
   /**
    * Resolve a @a Condition.
    * @param condition the @a Condition to resolve.
+   * @param errorDescription a string in which to store the error description in case of error.
    * @param readMessageFunc the function to call for immediate reading of a @a Message from the bus, or NULL.
    * @return @a RESULT_OK on success, or an error code.
    */