[PATCH 2/3] Misc style fixes and comments additions

[Dodji Seketeli <dodji seketeli org>]

Hello,

While hacking on the source code I stumbled accross style issues that I
fixed in the patch below.  Tested an applying that to master now.

Cheers.

        * src/common/nmv-asm-utils.h (FindFileAndReadLine, class
        ReadLine, ReadLine::operator()): Add comment.
        * src/common/nmv-asm-utils.cc (write_asm_instr, write_asm_instr):
        Add apidoc comment.
        * src/persp/dbgperspective/nmv-dbg-perspective.cc
        (DBGPerspective::on_activate_global_variables): Add ';' after
        NEMIVER_TRY, NEMIVER_CATCH.
        (DBGPerspective::connect_to_remote_target): Remove useless white
        spaces.
        * src/persp/dbgperspective/nmv-global-vars-inspector-dialog.h:
        Likewise.
        * src/persp/dbgperspective/nmv-load-core-dialog.h: Likewise.
        * src/persp/dbgperspective/nmv-open-file-dialog.h: Likewise.
        * src/persp/dbgperspective/nmv-proc-list-dialog.h: Likewise.
        * src/uicommon/nmv-locate-file-dialog.cc: Likewise.

Signed-off-by: Dodji Seketeli <dodji seketeli org>
---
 src/common/nmv-asm-utils.cc                        | 23 ++++++++++++++++++---
 src/common/nmv-asm-utils.h                         | 24 ++++++++++++++++++++--
 src/persp/dbgperspective/nmv-dbg-perspective.cc    |  7 +++----
 .../nmv-global-vars-inspector-dialog.h             |  2 --
 src/persp/dbgperspective/nmv-load-core-dialog.h    |  1 -
 src/persp/dbgperspective/nmv-open-file-dialog.h    |  1 -
 src/persp/dbgperspective/nmv-proc-list-dialog.h    |  1 -
 src/uicommon/nmv-locate-file-dialog.cc             |  1 -
 8 files changed, 45 insertions(+), 15 deletions(-)

diff --git a/src/common/nmv-asm-utils.cc b/src/common/nmv-asm-utils.cc
index 1443487..3c52a94 100644
--- a/src/common/nmv-asm-utils.cc
+++ b/src/common/nmv-asm-utils.cc
@@ -41,9 +41,16 @@ log_asm_insns (const std::list<common::Asm> &a_asm)
     }
 }
 
+/// Write an asm instruction to an output stream.
+///
+/// \param a_instr the asm instruction to write.
+///
+/// \param a_os the output stream to write the instruction to.
+///
+/// \return true upon successful completion, false otherwise.
 bool
 write_asm_instr (const common::AsmInstr &a_instr,
-                std::ostringstream &a_os)
+                 std::ostringstream &a_os)
 {
     a_os << a_instr.address ();
     a_os << "  ";
@@ -56,10 +63,20 @@ write_asm_instr (const common::AsmInstr &a_instr,
     return true;
 }
 
+/// Write an asm instruction to an output stream.
+///
+/// \param a_asm the asm instruction to write.
+///
+/// \param a_read the functor used to read source code lines in case
+/// the asm to write is mixed with higher level source code.
+///
+/// \param a_os the output stream to write the asm to.
+///
+/// \return true upon sucessful completion, false otherwise.
 bool
 write_asm_instr (const common::Asm &a_asm,
-                ReadLine &a_read,
-                std::ostringstream &a_os)
+                 ReadLine &a_read,
+                 std::ostringstream &a_os)
 {
     bool written = false;
 
diff --git a/src/common/nmv-asm-utils.h b/src/common/nmv-asm-utils.h
index 0cac127..885aab2 100644
--- a/src/common/nmv-asm-utils.h
+++ b/src/common/nmv-asm-utils.h
@@ -91,12 +91,22 @@ operator<< (Stream &a_out, const Asm &a_asm)
 
 void log_asm_insns (const std::list<common::Asm> &a_asm);
 
-typedef bool (* FindFileAndReadLine) (const UString &a_file_path,
+/// A pointer to ui_utils::find_file_and_read_line() function.
+typedef bool (* FindFileAndReadLine) (Gtk::Window &a_parent_window,
+                                     const UString &a_file_path,
                                      const std::list<UString> &a_where_to_look,
                                       list<UString> &a_sess_dirs,
                                       map<UString, bool> &a_ignore_paths,
                                      int a_line_number,
                                       std::string &a_line);
+
+/// This is a wrapper type around (a functor) for the call to
+/// ui_utils::find_file_and_read_line.
+///
+/// The function call operator of this functor read the line N of a
+/// given file F.  The functor has context to know where to look for
+/// the file F; otherwise it can ask the user (interactively) for
+/// help.
 class ReadLine
 {
  private:
@@ -112,7 +122,7 @@ class ReadLine
  public:
     ReadLine (const std::list<UString> &where_to_look,
              list<UString> &session_dirs,
-                  map<UString, bool> &ignore_paths,
+             map<UString, bool> &ignore_paths,
               FindFileAndReadLine read_line_func) :
     m_where_to_look (where_to_look),
       m_session_dirs (session_dirs),
@@ -121,6 +131,16 @@ class ReadLine
     {
     }
 
+    /// The function-call operator of the functor.
+    ///
+    /// \param a_file_path the file to look for.
+    ///
+    /// \param a_line_number the number of the line of \p a_file_path
+    /// to read.
+    ///
+    /// \param a_line the resulting line read.
+    ///
+    /// \return true iff a line was read.
     bool operator () (const UString &a_file_path,
                       int a_line_number,
                       std::string &a_line)
diff --git a/src/persp/dbgperspective/nmv-dbg-perspective.cc b/src/persp/dbgperspective/nmv-dbg-perspective.cc
index 6a7ff1b..dfff86b 100644
--- a/src/persp/dbgperspective/nmv-dbg-perspective.cc
+++ b/src/persp/dbgperspective/nmv-dbg-perspective.cc
@@ -2946,14 +2946,14 @@ DBGPerspective::on_activate_global_variables ()
 {
     LOG_FUNCTION_SCOPE_NORMAL_DD;
 
-    NEMIVER_TRY
+    NEMIVER_TRY;
 
     GlobalVarsInspectorDialog dialog (plugin_path (),
                                       debugger (),
                                       workbench ());
     dialog.run ();
 
-    NEMIVER_CATCH
+    NEMIVER_CATCH;
 }
 
 void
@@ -6359,9 +6359,8 @@ DBGPerspective::connect_to_remote_target ()
     // try to pre-fill the remote target dialog with the relevant info
     // if we have it.
     pre_fill_remote_target_dialog (dialog);
-    
-    int result = dialog.run ();
 
+    int result = dialog.run ();
     if (result != Gtk::RESPONSE_OK)
         return;
 
diff --git a/src/persp/dbgperspective/nmv-global-vars-inspector-dialog.h 
b/src/persp/dbgperspective/nmv-global-vars-inspector-dialog.h
index 47c5f4a..f4d4327 100644
--- a/src/persp/dbgperspective/nmv-global-vars-inspector-dialog.h
+++ b/src/persp/dbgperspective/nmv-global-vars-inspector-dialog.h
@@ -60,5 +60,3 @@ public:
 
 NEMIVER_END_NAMESPACE (nemiver)
 #endif //__NMV_GLOBAL_VARS_INSPECTOR_DIALOG_H__
-
-
diff --git a/src/persp/dbgperspective/nmv-load-core-dialog.h b/src/persp/dbgperspective/nmv-load-core-dialog.h
index 9c621e2..50849ed 100644
--- a/src/persp/dbgperspective/nmv-load-core-dialog.h
+++ b/src/persp/dbgperspective/nmv-load-core-dialog.h
@@ -55,4 +55,3 @@ public:
 NEMIVER_END_NAMESPACE (nemiver)
 
 #endif //__NMV_LOAD_CORE_DIALOG_H__
-
diff --git a/src/persp/dbgperspective/nmv-open-file-dialog.h b/src/persp/dbgperspective/nmv-open-file-dialog.h
index b69710e..2868f2b 100644
--- a/src/persp/dbgperspective/nmv-open-file-dialog.h
+++ b/src/persp/dbgperspective/nmv-open-file-dialog.h
@@ -55,4 +55,3 @@ public:
 NEMIVER_END_NAMESPACE (nemiver)
 
 #endif //__NMV_OPEN_FILE_DIALOG_H__
-
diff --git a/src/persp/dbgperspective/nmv-proc-list-dialog.h b/src/persp/dbgperspective/nmv-proc-list-dialog.h
index 1932740..6fde7a9 100644
--- a/src/persp/dbgperspective/nmv-proc-list-dialog.h
+++ b/src/persp/dbgperspective/nmv-proc-list-dialog.h
@@ -54,4 +54,3 @@ public:
 NEMIVER_END_NAMESPACE (nemiver)
 
 #endif //__NMV_PROC_LIST_DIALOG_H__
-
diff --git a/src/uicommon/nmv-locate-file-dialog.cc b/src/uicommon/nmv-locate-file-dialog.cc
index 3a609ff..68e1f48 100644
--- a/src/uicommon/nmv-locate-file-dialog.cc
+++ b/src/uicommon/nmv-locate-file-dialog.cc
@@ -128,4 +128,3 @@ LocateFileDialog::file_location (const UString &a_location)
 }
 
 }//end namespace nemiver
-
-- 
                Dodji