From 7bc46323e27b6a3a8807bf700e6b9925d888ddcc Mon Sep 17 00:00:00 2001
From: Marek Bel <marek.bel@posta.cz>
Date: Wed, 12 Sep 2018 18:35:26 +0200
Subject: [PATCH] Update pause print documentation.

---
 Firmware/Marlin_main.cpp | 42 +++++++++++++++++++++++++++++-----------
 Firmware/doxyfile        |  2 +-
 Firmware/ultralcd.cpp    |  5 ++++-
 3 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/Firmware/Marlin_main.cpp b/Firmware/Marlin_main.cpp
index 9d641c674..b09f398c9 100644
--- a/Firmware/Marlin_main.cpp
+++ b/Firmware/Marlin_main.cpp
@@ -464,8 +464,6 @@ bool no_response = false;
 uint8_t important_status;
 uint8_t saved_filament_type;
 
-// save/restore printing
-bool saved_printing = false;
 
 // save/restore printing in case that mmu was not responding 
 bool mmu_print_saved = false;
@@ -526,17 +524,20 @@ unsigned long chdkHigh = 0;
 boolean chdkActive = false;
 #endif
 
-// save/restore printing
-static uint32_t saved_sdpos = 0;
+//! @name RAM save/restore printing
+//! @{
+bool saved_printing = false; //!< Print is paused and saved in RAM
+static uint32_t saved_sdpos = 0; //!< SD card position, or line number in case of USB printing
 static uint8_t saved_printing_type = PRINTING_TYPE_SD;
 static float saved_pos[4] = { 0, 0, 0, 0 };
-// Feedrate hopefully derived from an active block of the planner at the time the print has been canceled, in mm/min.
+//! Feedrate hopefully derived from an active block of the planner at the time the print has been canceled, in mm/min.
 static float saved_feedrate2 = 0;
 static uint8_t saved_active_extruder = 0;
-static float saved_extruder_temperature = 0.0;
+static float saved_extruder_temperature = 0.0; //!< Active extruder temperature
 static bool saved_extruder_under_pressure = false;
 static bool saved_extruder_relative_mode = false;
-static int saved_fanSpeed = 0;
+static int saved_fanSpeed = 0; //!< Print fan speed
+//! @}
 
 //===========================================================================
 //=============================Routines======================================
@@ -2019,6 +2020,7 @@ static int setup_for_endstop_move(bool enable_endstops_now = true) {
     return l_feedmultiply;
 }
 
+//! @param original_feedmultiply feedmultiply to restore
 static void clean_up_after_endstop_move(int original_feedmultiply) {
 #ifdef ENDSTOPS_ONLY_FOR_HOMING
     enable_endstops(false);
@@ -8586,9 +8588,14 @@ void restore_print_from_eeprom() {
 #endif //UVLO_SUPPORT
 
 
-////////////////////////////////////////////////////////////////////////////////
-// save/restore printing
-
+//! @brief Immediately stop print moves
+//!
+//! Immediately stop print moves, save current extruder temperature and position to RAM.
+//! If printing from sd card, position in file is saved.
+//! If printing from USB, line number is saved.
+//!
+//! @param z_move
+//! @param e_move
 void stop_and_save_print_to_ram(float z_move, float e_move)
 {
 	if (saved_printing) return;
@@ -8773,6 +8780,14 @@ void stop_and_save_print_to_ram(float z_move, float e_move)
   }
 }
 
+//! @brief Restore print from ram
+//!
+//! Restore print saved by stop_and_save_print_to_ram(). Is blocking,
+//! waits for extruder temperature restore, then restores position and continues
+//! print moves.
+//! Internaly lcd_update() is called by wait_for_heater().
+//!
+//! @param e_move
 void restore_print_from_ram_and_continue(float e_move)
 {
 	if (!saved_printing) return;
@@ -8914,8 +8929,13 @@ void M600_check_state()
 		}
 }
 
+//! @brief Wait for user action
+//!
+//! Beep, manage nozzle heater and wait for user to start unload filament
+//! If times out, active extruder temperature is set to 0.
+//!
+//! @param HotendTempBckp Temperature to be restored for active extruder, after user resolves MMU problem.
 void M600_wait_for_user(float HotendTempBckp) {
-		//Beep, manage nozzle heater and wait for user to start unload filament
 
 		KEEPALIVE_STATE(PAUSED_FOR_USER);
 
diff --git a/Firmware/doxyfile b/Firmware/doxyfile
index 6fa1ef4fa..f38053027 100644
--- a/Firmware/doxyfile
+++ b/Firmware/doxyfile
@@ -453,7 +453,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
diff --git a/Firmware/ultralcd.cpp b/Firmware/ultralcd.cpp
index 7037d2f53..8b84cc4fa 100644
--- a/Firmware/ultralcd.cpp
+++ b/Firmware/ultralcd.cpp
@@ -1684,7 +1684,7 @@ void lcd_return_to_status()
 	menu_depth = 0;
 }
 
-
+//! @brief Pause print, disable nozzle heater, move to park position
 void lcd_pause_print()
 {
     lcd_return_to_status();
@@ -5458,6 +5458,9 @@ static void lcd_test_menu()
 }
 #endif //LCD_TEST
 
+//! @brief Resume paused print
+//! @todo It is not good to call restore_print_from_ram_and_continue() from function called by lcd_update(),
+//! as restore_print_from_ram_and_continue() calls lcd_update() internally.
 void lcd_resume_print()
 {
     lcd_return_to_status();