more comments on program notification

Author: Gin

SerialPrograms/CMakeLists.txt

@@ -2410,7 +2410,7 @@ if (MSVC)
 #    target_compile_options(SerialPrograms PRIVATE /arch:AVX2   /DPA_Arch_x64_AVX2)
 #    target_compile_options(SerialPrograms PRIVATE /arch:AVX512 /DPA_Arch_x64_AVX512)
 #    target_compile_options(SerialPrograms PRIVATE /arch:AVX512 /DPA_Arch_x64_AVX512GF)
-else()
+else() # macOS and Linux
     if (APPLE)
         # Get root path where Homebrew installs libraries. Example root path: "/opt/homebrew/",
         # where you can find libraries in "/opt/homebrew/lib/" and headers in "/opt/homebrew/include/".
@@ -2421,7 +2421,7 @@ else()
         # Get ONNX Runtime paths
         target_include_directories(SerialPrograms PRIVATE ${HOMEBREW_PREFIX}/include/onnxruntime)
         target_link_libraries(SerialPrograms PRIVATE ${HOMEBREW_PREFIX}/lib/libonnxruntime.dylib)
-    else()
+    else() # Linux
         # Instructions took from https://github.com/microsoft/onnxruntime/discussions/6489
         # Step 1: Download the file
         file(DOWNLOAD

SerialPrograms/Source/CommonFramework/Notifications/ProgramNotifications.cpp

@@ -89,7 +89,7 @@ void send_raw_notification(
     const std::vector<std::pair<std::string, std::string>>& messages,
     const ImageAttachment& image
 ){
-    std::shared_ptr<PendingFileSend> file(new PendingFileSend(logger, image));
+    std::shared_ptr<PendingFileSend> file = std::make_shared<PendingFileSend>(logger, image);
     bool hasFile = !file->filepath().empty();
 
     JsonObject embed;
@@ -147,7 +147,7 @@ void send_raw_notification(
     const std::vector<std::pair<std::string, std::string>>& messages,
     const std::string& filepath
 ){
-    std::shared_ptr<PendingFileSend> file(new PendingFileSend(filepath, true));
+    std::shared_ptr<PendingFileSend> file = std::make_shared<PendingFileSend>(filepath, true);
     bool hasFile = !file->filepath().empty();
 
     JsonObject embed;

SerialPrograms/Source/CommonFramework/Notifications/ProgramNotifications.h

@@ -21,7 +21,16 @@ class ProgramEnvironment;
 
 
 
-//  Raw Notification
+//  Send raw Discord notification according to the notification settings.
+//  Can control the message sidebar color, message title, and message body.
+//  messages: vector<pair<string, string>>, the sections of the Discord message.
+//    The first string in the pair is the section title (will shown as bold) while the second
+//    string is the section content.
+//    e.g. {{"Message:", {"This is a message."}}} will shown as (in Markdown):
+//    **Message**
+//    This is a message.
+//  The function will add an additional section "Powered By".
+//  filepath: send the file as a message attachment.
 void send_raw_program_notification_with_file(
     Logger& logger, EventNotificationOption& settings,
     Color color,
@@ -30,6 +39,20 @@ void send_raw_program_notification_with_file(
     const std::vector<std::pair<std::string, std::string>>& messages,
     const std::string& filepath
 );
+
+//  Send raw Discord notification according to the notification settings.
+//  Can control the message sidebar color, message title, and message body.
+//  messages: vector<pair<string, string>>, the sections of the Discord message.
+//    The first string in the pair is the section title (will shown as bold) while the second
+//    string is the section content.
+//    e.g. {{"Message:", {"This is a message."}}} will shown as (in Markdown):
+//    **Message**
+//    This is a message.
+//  The function will add an additional section "Powered By".
+//  image: if not empty, send the screenshot image as part of the message according to the
+//    notification settings.
+//  keep_file: if true, the sent image will be saved to the screenshot dir on disk. Otherwise, it
+//    will be saved to the program TEMP_FOLDER.
 void send_raw_program_notification(
     Logger& logger, EventNotificationOption& settings,
     Color color,
@@ -41,7 +64,19 @@ void send_raw_program_notification(
 
 
 
-//  Program notification with stats.
+//  Send custom Discord notification according to the notification settings.
+//  Can control the message sidebar color, message title, and message body.
+//  messages: vector<pair<string, string>>, the sections of the Discord message.
+//    The first string in the pair is the section title (will shown as bold) while the second
+//    string is the section content.
+//    e.g. {{"Message:", {"This is a message."}}} will shown as (in Markdown):
+//    **Message**
+//    This is a message.
+//  The function will add additional sections: "Current Session", "Historical Stats"
+//    and "Powered By".
+//  current_stats_addendum: add additional message at the end of the "Current Session" section
+//  where it shows the current program stats message generated by StatsTracker.
+//  filepath: send the file as a message attachment.
 void send_program_notification_with_file(
     ProgramEnvironment& env, EventNotificationOption& settings,
     Color color,
@@ -50,6 +85,23 @@ void send_program_notification_with_file(
     const std::string& current_stats_addendum,
     const std::string& filepath
 );
+
+//  Send custom Discord notification according to the notification settings.
+//  Can control the message sidebar color, message title, and message body.
+//  messages: vector<pair<string, string>>, the sections of the Discord message.
+//    The first string in the pair is the section title (will shown as bold) while the second
+//    string is the section content.
+//    e.g. {{"Message:", {"This is a message."}}} will shown as (in Markdown):
+//    **Message**
+//    This is a message.
+//  The function will add additional sections: "Current Session", "Historical Stats"
+//    and "Powered By".
+//  current_stats_addendum: add additional message at the end of the "Current Session" section
+//  where it shows the current program stats message generated by StatsTracker.
+//  image: if not empty, send the screenshot image as part of the message according to the
+//    notification settings.
+//  keep_file: if true, the sent image will be saved to the screenshot dir on disk. Otherwise, it
+//    will be saved to the program TEMP_FOLDER.
 bool send_program_notification(
     ProgramEnvironment& env, EventNotificationOption& settings,
     Color color,
@@ -61,24 +113,42 @@ bool send_program_notification(
 
 
 
-//  Other common program notification types.
+//  Send Discord notification of the current program status according to the notification settings.
+//  Can send additional message and screenshot image.
+//  keep_file: if true, the sent image will be saved to the screenshot dir on disk. Otherwise, it
+//    will be saved to the program TEMP_FOLDER.
 void send_program_status_notification(
     ProgramEnvironment& env, EventNotificationOption& settings,
     const std::string& message = "",
     const ImageViewRGB32& image = ImageViewRGB32(), bool keep_file = false
 );
 
+//  Send Discord notification that the program has finished according to the notification settings.
+//  Can send additional message and screenshot image.
+//  keep_file: if true, the sent image will be saved to the screenshot dir on disk. Otherwise, it
+//    will be saved to the program TEMP_FOLDER.
 void send_program_finished_notification(
     ProgramEnvironment& env, EventNotificationOption& settings,
     const std::string& message = "",
     const ImageViewRGB32& image = ImageViewRGB32(), bool keep_file = false
 );
 
+//  Send Discord notification that the program has encountered a recoverable error according to the
+//  notification settings.
+//  Can send additional message and screenshot image.
+//  keep_file: if true, the sent image will be saved to the screenshot dir on disk. Otherwise, it
+//    will be saved to the program TEMP_FOLDER.
 void send_program_recoverable_error_notification(
     ProgramEnvironment& env, EventNotificationOption& settings,
     const std::string& message,
     const ImageViewRGB32& image = ImageViewRGB32(), bool keep_file = false
 );
+
+//  Send Discord notification that the program has a fatal error according to the notification
+//  settings.
+//  Can send additional message and screenshot image.
+//  keep_file: if true, the sent image will be saved to the screenshot dir on disk. Otherwise, it
+//    will be saved to the program TEMP_FOLDER.
 void send_program_fatal_error_notification(
     ProgramEnvironment& env, EventNotificationOption& settings,
     const std::string& message,