Documentation

Summary

Minimal documentation is written now and shows up on docs.indiscale.com.

Focus

• Is the documentation correct and complete?
• Is the minimal example enough for users to get started?
• Is it acceptable that the API documentation is outside sphinx?

Test Environment

• Build: make doc_clean; make doc
• Open the html: xdg-open build/doc/html/index.html
• To test the pages build: download the artifact directory from the pipeline, extract it and inspect the index.html inside.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass -> integration test is allowed to fail since no corresponding repo exists there.
• Reference related Issues: for caosdb/customers/lfpb/management#417
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there spezifications? Are they satisfied?

For further good practices have a look at our review guidelines.

TODO

• Add description to README_SETUP.md: how to run unit tests locally

src/lib/maoxdb.cpp

@@ -198,9 +198,7 @@ auto mxFromCaosDBParents(const ce::Parents &parents) -> mxArray * {
     auto parent = parents.at(i);
     mxSetField(result, i, "id", mxCreateString(parent.GetId().c_str()));
     mxSetField(result, i, "name", mxCreateString(parent.GetName().c_str()));
-    // FIXME Add again once upstream is ready.
-    // mxSetField(result, i, "description",
-    // mxCreateString(parent.GetDescription().c_str()));
+    mxSetField(result, i, "description", mxCreateString(parent.GetDescription().c_str()));
   }
   return result;
 }
@@ -255,24 +253,27 @@ auto mxFromCaosDBMessages(const ce::Messages &messages) -> mxArray * {
 auto mxFromDataType(const ce::DataType &data_type) -> mxArray * {
   namespace ce = ce;
 
-  auto is_list = mxScalarLOGICAL(data_type.IsList());
   mxArray *dtype_name;
-  mxArray *is_reference;
+  auto is_list = mxScalarLOGICAL(data_type.IsList());
+  auto is_reference = mxScalarLOGICAL(data_type.IsReference());
   if (data_type.IsList()) {
-    const auto &list_datatype = data_type.AsList();
+    const auto &list_datatype = data_type.GetAsList();
     is_reference = mxScalarLOGICAL(list_datatype.IsListOfReference());
     if (list_datatype.IsListOfReference()) {
       dtype_name = mxCreateString(list_datatype.GetReferenceDataType().GetName().c_str());
-    } else {
+    } else if (list_datatype.IsListOfAtomic()) {
       dtype_name = mxEnumToString<ce::AtomicDataType>(list_datatype.GetAtomicDataType());
-    }
-  } else {
-    is_reference = mxScalarLOGICAL(data_type.IsReference());
-    if (data_type.IsReference()) {
-      dtype_name = mxCreateString(data_type.AsReference().GetName().c_str());
     } else {
-      dtype_name = mxEnumToString<ce::AtomicDataType>(data_type.AsAtomic());
+      throw std::logic_error(string("Unexpected data type: " + data_type.ToString()));
     }
+  } else if (data_type.IsReference()) {
+    dtype_name = mxCreateString(data_type.GetAsReference().GetName().c_str());
+  } else if (data_type.IsAtomic()) {
+    dtype_name = mxEnumToString<ce::AtomicDataType>(data_type.GetAsAtomic());
+  } else if (data_type.ToString() == "{}") {
+    return mxEmptySparse(); // Workaround to denote a Null value: sparse array
+  } else {
+    throw std::logic_error(string("Unexpected data type: " + data_type.ToString()));
   }
 
   // clang-format off
@@ -297,18 +298,18 @@ auto mxFromValue(const ce::Value &value) -> mxArray * {
   if (value.IsNull()) {
     return mxEmptySparse();      // Workaround to denote a Null value: sparse array
   } else if (value.IsString()) { // Scalars are converted to normal arrays.
-    return mxCreateString(value.AsString().c_str());
+    return mxCreateString(value.GetAsString().c_str());
   } else if (value.IsDouble()) {
-    return mxScalarDOUBLE(value.AsDouble());
+    return mxScalarDOUBLE(value.GetAsDouble());
   } else if (value.IsBool()) {
-    return mxScalarLOGICAL(value.AsBool());
-  } else if (value.IsInteger()) {
-    return mxScalarINT64(value.AsInteger());
-  } else if (!value.IsList()) {
+    return mxScalarLOGICAL(value.GetAsBool());
+  } else if (value.IsInt64()) {
+    return mxScalarINT64(value.GetAsInt64());
+  } else if (!value.IsVector()) {
     throw std::logic_error(string("Unexpected value type: " + value.ToString()));
   }
   // It's a list now -> convert to cell array always.
-  auto list = value.AsList();
+  auto list = value.GetAsVector();
   auto *result = mxCreateCellArray(0, (mwSize *)nullptr);
   if (list.empty()) { // Empty list: empty cell array
     return result;
@@ -318,25 +319,25 @@ auto mxFromValue(const ce::Value &value) -> mxArray * {
   if (list_value.IsString()) { // String
     result = mxCreateCellArray(2, dims.data());
     for (size_t i = 0; i < list.size(); ++i) {
-      mxSetCell(result, i, mxCreateString(list[i].AsString().c_str()));
+      mxSetCell(result, i, mxCreateString(list[i].GetAsString().c_str()));
     }
   } else if (list_value.IsBool()) { // Bool
     result = mxCreateLogicalArray(2, dims.data());
     auto *data = static_cast<mxLogical *>(mxGetData(result));
     for (size_t i = 0; i < list.size(); ++i) {
-      data[i] = list[i].AsBool();
+      data[i] = list[i].GetAsBool();
     }
-  } else if (list_value.IsInteger()) { // Int
+  } else if (list_value.IsInt64()) { // Int
     result = mxCreateNumericArray(2, dims.data(), mxINT64_CLASS, mxREAL);
     auto *data = static_cast<INT64_T *>(mxGetData(result));
     for (size_t i = 0; i < list.size(); ++i) {
-      data[i] = list[i].AsInteger();
+      data[i] = list[i].GetAsInt64();
     }
   } else if (list_value.IsDouble()) { // Double
     result = mxCreateNumericArray(2, dims.data(), mxDOUBLE_CLASS, mxREAL);
     auto *data = static_cast<double *>(mxGetData(result));
     for (size_t i = 0; i < list.size(); ++i) {
-      data[i] = list[i].AsInteger();
+      data[i] = list[i].GetAsDouble();
     }
   } else {
     throw std::logic_error("Unexpected list value type");
@@ -367,11 +368,16 @@ void assignEntityDataFromMx(ce::Entity &entity, const mxArray *array, const mwSi
     entity.SetFilePath(mxGetStdString(mxGetField(array, index, "filepath")));
     entity.SetLocalPath(mxGetStdString(mxGetField(array, index, "localpath")));
   }
-  // TODO Remove existing parents and properties.
   CAOSDB_LOG_TRACE(logger_name) << "parents & properties";
+  for (size_t i = entity.GetParents().size(); i > 0; i--) {
+    entity.RemoveParent(i - 1);
+  }
   for (auto parent : parentsFromMx(mxGetField(array, index, "parents"))) {
     entity.AppendParent(parent);
   }
+  for (size_t i = entity.GetProperties().size(); i > 0; i--) {
+    entity.RemoveProperty(i - 1);
+  }
   for (auto &property : propertiesFromMx(mxGetField(array, index, "properties"))) {
     entity.AppendProperty(property);
   }
@@ -489,10 +495,14 @@ auto dataTypeFromMx(const mxArray *datatypeArray) -> ce::DataType {
   auto dtype_name = mxGetStdString(mxGetField(datatypeArray, 0, "dtypeName"));
 
   ce::DataType dtype;
-  if (is_reference) {
-    dtype = ce::DataType(dtype_name, is_list);
+  if (is_reference && is_list) {
+    dtype = ce::DataType::ListOf(dtype_name);
+  } else if (is_reference) {
+    dtype = ce::DataType(dtype_name);
+  } else if (is_list) {
+    dtype = ce::DataType::ListOf(cu::getEnumValueFromName<ce::AtomicDataType>(dtype_name));
   } else {
-    dtype = ce::DataType(cu::getEnumValueFromName<ce::AtomicDataType>(dtype_name), is_list);
+    dtype = ce::DataType(cu::getEnumValueFromName<ce::AtomicDataType>(dtype_name));
   }
 
   return dtype;