Documentation to code fixes

Author: DraTeots

docs-audit-report.md

@@ -13,18 +13,18 @@ def add_condition(run, name, value, replace=False)
 There is a common situation when one has a collection of values (E.g. after parsing a file), for this case there is a handy function that allows to add many conditions values at one time.
 
 ```python
-def add_conditions(run, name_values, replace=False)
+def add_conditions(run, key_values, replace=False)
 ```
 
-The ```name_values``` could be a dictionary or list of name-value pairs:
+The ```key_values``` could be a dictionary or list of name-value pairs:
 
 ```python
 # dict
-name_values = {"name1":value1, "name2":value2, ...}
+key_values = {"name1":value1, "name2":value2, ...}
 # list of tuples
-name_values = [("name1",value1), ("name2",value2), ...]
+key_values = [("name1",value1), ("name2",value2), ...]
 # list of lists
-name_values = [["name1",value1], ["name2",value2], ...]
+key_values = [["name1",value1], ["name2",value2], ...]
 ```
 
 **(!) performance:** ```add_conditions``` tries to use as less transactions as possible to check and commit all values. So for it provides a big performance gain vs calling ```add_condition``` for each value separately
@@ -69,10 +69,10 @@ Lets example it:
 db = RCDBProvider("sqlite:///example.db")
 
 # Crete condition types
-db.create_condition_type("int_val", ConditionType.INT_FIELD)
-db.create_condition_type("float_val", ConditionType.FLOAT_FIELD)
-db.create_condition_type("bool_val", ConditionType.BOOL_FIELD)
-db.create_condition_type("string_val", ConditionType.STRING_FIELD)
+db.create_condition_type("int_val", ConditionType.INT_FIELD, "Integer value example")
+db.create_condition_type("float_val", ConditionType.FLOAT_FIELD, "Float value example")
+db.create_condition_type("bool_val", ConditionType.BOOL_FIELD, "Bool value example")
+db.create_condition_type("string_val", ConditionType.STRING_FIELD, "String value example")
 
 # Add values to run 1
 db.add_condition(1, "int_val", 1000)
@@ -83,16 +83,16 @@ db.add_condition(1, "string_val", "test test")
 # Read values for run 1 and use them
 
 condition = db.get_condition(1, "int_val")
-print condition.value
+print(condition.value)
 
 condition = db.get_condition(1, "float_val")
-print condition.value
+print(condition.value)
 
 condition = db.get_condition(1, "bool_val")
-print condition.value
+print(condition.value)
 
 condition = db.get_condition(1, "string_val")
-print condition.value
+print(condition.value)
 ```
 
 The output:
@@ -110,7 +110,7 @@ ConditionType.TIME_FIELD is used for time fields. Standard python datetime is us
 
 ```python
 # Create condition type
-db.create_condition_type("my_val", ConditionType.TIME_FIELD)
+db.create_condition_type("my_val", ConditionType.TIME_FIELD, "Time value example")
 
 # Add value and time information
 db.add_condition(1, "my_val", datetime(2015, 10, 10, 15, 28, 12, 111111))
@@ -125,15 +125,15 @@ RCDB conditions API doesn't provide mechanisms of converting objects to JSON and
 For arrays it is done easily by json module.
 
 
-The example from [[https://docs.python.org/2/library/json.html python 2.7 documentation]]:
+The example from [[https://docs.python.org/3/library/json.html python documentation]]:
 
 ```
 >>> import json
 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
  '["foo", {"bar": ["baz", null, 1.0, 2]}]'
 
 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
- [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
+ ['foo', {'bar': ['baz', None, 1.0, 2]}]
 ```
 
 So, serialization is on the users side. It is done to have a better control over serialization.
@@ -151,8 +151,8 @@ from rcdb.model import ConditionType
 db = RCDBProvider("sqlite:///example.db")
 
 # Create condition type
-db.create_condition_type("list_data", ConditionType.JSON_FIELD)
-db.create_condition_type("dict_data", ConditionType.JSON_FIELD)
+db.create_condition_type("list_data", ConditionType.JSON_FIELD, "Data list")
+db.create_condition_type("dict_data", ConditionType.JSON_FIELD, "Data dict")
 
 list_to_store = [1, 2, 3]
 dict_to_store = {"x": 1, "y": 2, "z": 3}
@@ -165,19 +165,19 @@ db.add_condition(1, "dict_data", json.dumps(dict_to_store))
 restored_list = json.loads(db.get_condition(1, "list_data").value)
 restored_dict = json.loads(db.get_condition(1, "dict_data").value)
 
-print restored_list
-print restored_dict
+print(restored_list)
+print(restored_dict)
 
-print restored_dict["x"]
-print restored_dict["y"]
-print restored_dict["z"]
-python
+print(restored_dict["x"])
+print(restored_dict["y"])
+print(restored_dict["z"])
+```
 
 The output is:
 
 ```
 [1, 2, 3]
-{u'y': 2, u'x': 1, u'z': 3}
+{'y': 2, 'x': 1, 'z': 3}
 1
 2
 3
@@ -187,30 +187,28 @@ The output is:
 The example is located at
 
 ```
-$RCDB_HOME/python/example_conditions_store_array.py
+$RCDB_HOME/python/examples/11_crete_conditions_store_array.py
 ```
 
 and can be run as:
 ```bash
-python $RCDB_HOME/python/create_empty_sqlite.py example.db
-python $RCDB_HOME/python/example_conditions_store_array.py
+python $RCDB_HOME/python/examples/11_crete_conditions_store_array.py
 ```
 
-As one can mention unicode string is returned as unicode after json deserialization (look at u"x" instead of just "x").
-It is not a problem if you just work with this array, because python acts seamlessly with unicode strings.
-As you can see in example, we use usual string "x" in restored_dict["x"] and it just works.
-
-If it is a problem, there is a
-[[http://stackoverflow.com/questions/956867/how-to-get-string-objects-instead-of-unicode-ones-from-json-in-python stackoverlow question on that]]
+Run without arguments it creates an in-memory database. You can also pass a
+connection string to use a file-based SQLite database, e.g.
+`python $RCDB_HOME/python/examples/11_crete_conditions_store_array.py sqlite:///example.db`.
 
-Using pyYAML to deserialize to strings looks easy.
+In Python 3 all strings are unicode, so strings returned after json deserialization are
+ordinary `str` objects. As you can see in the example, we use the usual string "x" in
+restored_dict["x"] and it just works.
 
 
 
 ### Custom python objects
 
-To save custom python objects to database, jsonpickle package could be used. It is an open source project available
-via pip install. It is not shipped with RCDB at the moment.
+To save custom python objects to database, jsonpickle package could be used. It is an open source project
+that can be installed via the package manager. It is not shipped with RCDB at the moment.
 
 ```python
 from rcdb.provider import RCDBProvider
@@ -228,7 +226,7 @@ class Cat(object):
 db = RCDBProvider("sqlite:///example.db")
 
 # Create condition type
-db.create_condition_type("cat", ConditionType.JSON_FIELD)
+db.create_condition_type("cat", ConditionType.JSON_FIELD, "A cat object")
 
 
 # Create a cat and store in in the DB for run 1
@@ -239,11 +237,11 @@ db.add_condition(1, "cat", jsonpickle.encode(cat))
 condition = db.get_condition(1, "cat")
 loaded_cat = jsonpickle.decode(condition.value)
 
-print "How cat is stored in DB:"
-print condition.value
-print "Deserialized cat:"
-print "name:", loaded_cat.name
-print "mice_eaten:", loaded_cat.mice_eaten
+print("How cat is stored in DB:")
+print(condition.value)
+print("Deserialized cat:")
+print("name:", loaded_cat.name)
+print("mice_eaten:", loaded_cat.mice_eaten)
 ```
 
 The result:
@@ -261,6 +259,14 @@ mice_eaten: 1230
 
 jsonpickle installation:
 
+RCDB uses [uv](https://docs.astral.sh/uv/) as its package manager. To add jsonpickle to the project:
+
+```
+uv add jsonpickle
+```
+
+Alternatively, with plain pip:
+
 system level:
 
 ```

docs/Adding-condition-values.md

@@ -44,7 +44,7 @@ That also means that MySQL and SQLite libraries should be linked to the applicat
 
 In order for your code to build ensure flags/configuration:
 
-* There is at lease C++11 support enabled and stdc++ library linked. This means that probably minimum GCC version to be used is 4.8:
+* There is at least C++11 support enabled and stdc++ library linked. This means that probably minimum GCC version to be used is 4.8:
 
     ```-std=c++11 -lstdc++```
 
@@ -96,7 +96,7 @@ The example shows how to get values from RCDB:
 Connection con("mysql://rcdb@hallddb/rcdb");
 
 // Get event_count for run 10173
-auto cnd = prov.GetCondition(10173, "event_count");
+auto cnd = con.GetCondition(10173, "event_count");
 
 // Check event_count has a value for the run
 if(!cnd) {
@@ -116,7 +116,7 @@ bool ToBool();                         /// For bool or int in DB
 double ToDouble();                     /// For Double or int in DB
 std::string ToString();                /// For Json, String or Blob
 time_point<system_clock> ToTime();     /// For time value
-rapidjson::Document ToJsonDocument();  /// For JSon document
+rapidjson::Document ToJsonDocument();  /// DEPRECATED: use json ToJson() instead. For JSon document
 
 rcdb::ValueTypes GetValueType();       /// Returns the type enum
 ```
@@ -144,21 +144,25 @@ RCDB_TEST_CONNECTION="sqlite:///cpp_test.sqlite" ./build/test_rcdb_cpp
 Examples are located in the [$RCDB_HOME/cpp/examples](https://github.com/JeffersonLab/rcdb/tree/main/cpp/examples) folder
 and are built as the `examples_*` targets by the `cmake --build build` command above.
 
-After examples are built they are located in `$RCDB_HOME/cpp/bin` directory named as `exmpl_<...>`
+After examples are built they are located in the `cpp/build` directory, named after their CMake
+targets (e.g. `examples_trigger_params`). There is no separate install step or custom output directory.
 
 <br>
 
 **List of examples:**
 
-* [simple.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/simple.cpp) - Simple condition readout
-* [get_trigger_params.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/get_trigger_params.cpp) - Versatile data readout example. It includes:  
+* [simple.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/simple.cpp) - Simple condition readout. Note: this example has no CMake target and is not built by `cmake --build build`; compile it manually with `gcc` as shown in the Installation section.
+* [get_trigger_params.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/get_trigger_params.cpp) (target `examples_trigger_params`) - Versatile data readout example. It includes:  
      * Reading conditions
      * Working with JSON serialized objects
      * Getting RCDB stored files contents
      * Working with config file parser
-* [write_conditions.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/write_conditions.cpp) - Writing conditions to RCDB from C++. It includes:  
-     * Using WriteConnection
+* [get_fadc_masks.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/get_fadc_masks.cpp) (target `examples_fadc_masks`) - Reading FADC masks
+* [write_conditions.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/write_conditions.cpp) (target `examples_write_conditions`) - Writing conditions to RCDB from C++. It includes:  
+     * Using WritingConnection
      * Adding condition values of different types
+* [write_array_to_json.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/write_array_to_json.cpp) (target `examples_write_array_to_json`) - Writing an array serialized to JSON
+* [write_objects_to_json.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/write_objects_to_json.cpp) (target `examples_write_objects_to_json`) - Writing objects serialized to JSON
 
 
 

docs/Cpp.md

@@ -4,8 +4,8 @@ Lets look ''create_condition_type'' from the example above (we add parameter nam
 
 ```python
 db.create_condition_type(name="my_val",
-                         value_type,
-                         description)
+                         value_type=value_type,
+                         description=description)
 ```
 
 **name** - The first parameter is condition name. When we say "event_count for run 100", "event_count" is that name.
@@ -36,4 +36,4 @@ Names are just strings. RCDB doesn't provide special treatment of slashes '/' or
 More examples of how to use types are presented in the next section
 
 
-**description** - 255 chars max human readable description, that other users can see. It is optional but it is very good practice to fill it.
+**description** - 255 chars max human readable description, that other users can see. It is a required argument, and it is very good practice to fill it with something meaningful.