add common

andrewbytecoder · andrewbytecoder · commit f655b6216490 · 2024-09-06T16:37:00.000+08:00
diff --git a/inc/dlms_bash.h b/inc/dlms_bash.h
@@ -1,6 +1,11 @@
-//
-// Created by andrew on 2022/2/21.
-//
+/**
+ * @file IContext.h
+ * @brief Interface for context operations in a system.
+ *
+ * This file contains the IContext interface which provides
+ * methods to initialize, start, stop, reset processes, and
+ * manage plugins.
+ */
 
 #ifndef DLMS_DLMS_BASH_H
 #define DLMS_DLMS_BASH_H
@@ -11,49 +16,77 @@
 
 
 class Plugin;
+/**
+ * @brief Interface for context operations.
+ *
+ * This class defines an interface for managing the lifecycle of 
+ * a process and handling plugins. 
+ */
 class IContext {
 public:
 
 
 public:
+    /// Destructor
     virtual ~IContext() = default;
 
     /**
-     * @brief 主进程初始化
+     * @brief Initializes the main process.
      *
-     * @return 0:成功，其他：失败
+     * This method is responsible for setting up the initial state
+     * of the main process.
+     *
+     * @return 0 if success, other values indicate failure.
      */
     virtual Status Init() = 0;
 
     /**
-     * @brief 启动主进程
+     * @brief Starts the main process.
+     *
+     * This method will start the execution of the main process.
      *
-     * @return 0:成功，其他：失败
+     * @return 0 if success, other values indicate failure.
      */
     virtual Status Start() = 0;
 
     /**
-     * @brief 停止主进程
+     * @brief Stops the main process.
+     *
+     * This method is called to stop the execution of the main process.
      *
-     * @return 0:成功，其他：失败
+     * @return 0 if success, other values indicate failure.
      */
     virtual Status Stop() = 0;
 
     /**
-     * @brief 退出主进程
+     * @brief Resets the main process.
      *
-     * @return 0:成功，其他：失败
+     * This method will reset the main process state.
+     *
+     * @return 0 if success, other values indicate failure.
      */
     virtual Status Reset() = 0;
 
     /**
-     * @brief 获取插件对象
+     * @brief Gets a plugin object.
+     *
+     * This method retrieves a plugin instance based on the plugin name
+     * and type provided.
      *
-     * @return nullptr:失败，其他：成功
+     * @param[in] pluginName The name of the plugin.
+     * @param[in] type The type of the plugin.
+     * @return A pointer to the plugin object if found, nullptr otherwise.
      */
     virtual Plugin *GetPlugin(std::string &pluginName, std::string &type) = 0;
 
-    // 将需要工作的线程放到Push里面
+    /**
+     * @brief Dispatches a work function to a thread.
+     *
+     * This method assigns a work function to be executed by a thread.
+     *
+     * @param[in] workFunction The function to be executed by the thread.
+     * @return 0 if success, other values indicate failure.
+     */
     virtual Status Dispatch(Func workFunction) = 0;
 };
 
diff --git a/inc/dlms_error.h b/inc/dlms_error.h
@@ -11,7 +11,18 @@
 #define OK 0
 #define MALLOC_FAILED 1
 
-
+/**
+ * @brief Status codes used throughout the program.
+ *
+ * These enum values represent the various status codes 
+ * that functions might return, providing a clear and 
+ * type-safe way to handle these return values.
+ */
+// enum class Status : int32_t {
+//     ERROR = -1,    ///< General error
+//     OK = 0,        ///< Success
+//     MALLOC_FAILED = 1 ///< Memory allocation failed
+// };
 
 
 
diff --git a/inc/dlms_macro.h b/inc/dlms_macro.h
@@ -7,5 +7,20 @@
 
 #define POINTER_SAFE(lp)        ((nullptr == (lp)) ? "null" : (lp))
 
+/**
+ * @brief Utility function to convert a pointer to a safe string representation.
+ *
+ * This function checks if the given pointer is nullptr and returns a string 
+ * indicating the pointer state.
+ *
+ * @tparam T Type of the pointer.
+ * @param ptr Pointer to be checked.
+ * @return "null" if the pointer is nullptr; the original pointer otherwise.
+ */
+template <typename T>
+constexpr const char* pointerSafe(T* ptr) {
+    return (nullptr == ptr) ? "null" : reinterpret_cast<const char*>(ptr);
+}
+
 
 #endif //DLMS_DLMS_MACRO_H
