Fl_Help_View: Reformat and comments

2 files changed, 94 insertions, 56 deletions

diff --git a/FL/Fl_Help_View.H b/FL/Fl_Help_View.H
index ca23196b3..9e486abec 100644
--- a/FL/Fl_Help_View.H
+++ b/FL/Fl_Help_View.H
@@ -253,8 +253,6 @@ class FL_EXPORT Fl_Help_View : public Fl_Group
   void          add_link(const std::string &link, int xx, int yy, int ww, int hh);
   void          add_target(const std::string &n, int yy);
   int           do_align(Fl_Help_Block *block, int line, int xx, int a, int &l);
-protected:
-  void          draw() override;
 private:
   void          format();
   void          format_table(int *table_width, int *columns, const char *table);
@@ -264,8 +262,6 @@ private:
   Fl_Color      get_color(const char *n, Fl_Color c);
   Fl_Shared_Image *get_image(const char *name, int W, int H);
   int           get_length(const char *l);
-public:
-  int           handle(int) override;
 private:
 
   void          hv_draw(const char *t, int x, int y, int entity_extra_length = 0);
@@ -276,44 +272,25 @@ private:
   std::shared_ptr<Link> find_link(int, int);
   void          follow_link(std::shared_ptr<Link>);
 
+protected:
+  void          draw() override;
+
 public:
 
   static const char *copy_menu_text;
 
   Fl_Help_View(int xx, int yy, int ww, int hh, const char *l = 0);
-  ~Fl_Help_View();
-  /** Returns the current directory for the text in the buffer. */
-  const char    *directory() const { if (directory_[0]) return (directory_);
-                                        else return ((const char *)0); }
-  /** Returns the current filename for the text in the buffer. */
-  const char    *filename() const { if (filename_[0]) return (filename_);
-                                        else return ((const char *)0); }
+  ~Fl_Help_View() override;
+
+  int handle(int) override;
+  void resize(int,int,int,int) override;
+
+  const char *filename() const;
+  const char *directory() const;
+  
   int           find(const char *s, int p = 0);
-  /**
-    This method assigns a callback function to use when a link is
-    followed or a file is loaded (via Fl_Help_View::load()) that
-    requires a different file or path.
-
-    The callback function receives a pointer to the Fl_Help_View
-    widget and the URI or full pathname for the file in question.
-    It must return a pathname that can be opened as a local file or NULL:
-
-    \code
-    const char *fn(Fl_Widget *w, const char *uri);
-    \endcode
-
-    The link function can be used to retrieve remote or virtual
-    documents, returning a temporary file that contains the actual
-    data. If the link function returns NULL, the value of
-    the Fl_Help_View widget will remain unchanged.
-
-    If the link callback cannot handle the URI scheme, it should
-    return the uri value unchanged or set the value() of the widget
-    before returning NULL.
-  */
-  void          link(Fl_Help_Func *fn) { link_ = fn; }
+  void          link(Fl_Help_Func *fn);
   int           load(const char *f);
-  void          resize(int,int,int,int) override;
   /** Gets the size of the help view. */
   int           size() const { return (size_); }
   void          size(int W, int H) { Fl_Widget::size(W, H); }
diff --git a/src/Fl_Help_View.cxx b/src/Fl_Help_View.cxx
index 1a0e28fb5..cf22ba277 100644
--- a/src/Fl_Help_View.cxx
+++ b/src/Fl_Help_View.cxx
@@ -3188,9 +3188,11 @@ Fl_Help_View::handle(int event) // I - Event to handle
   return (Fl_Group::handle(event));
 }
 
+
 /**
-  The constructor creates the Fl_Help_View widget at the specified
-  position and size.
+ \brief Creates the Fl_Help_View widget at the specified position and size.
+ \param[in] xx, yy, ww, hh Position and size of the widget
+ \param[in] l Label for the widget, can be NULL
 */
 Fl_Help_View::Fl_Help_View(int        xx,       // I - Left position
                            int        yy,       // I - Top position
@@ -3247,10 +3249,11 @@ Fl_Help_View::Fl_Help_View(int        xx,       // I - Left position
 }
 
 
-/** Destroys the Fl_Help_View widget.
+/** 
+ \brief Destroys the Fl_Help_View widget.
 
-  The destructor destroys the widget and frees all memory that has been
-  allocated for the current document.
+ The destructor destroys the widget and frees all memory that has been
+ allocated for the current document.
 */
 Fl_Help_View::~Fl_Help_View()
 {
@@ -3259,6 +3262,68 @@ Fl_Help_View::~Fl_Help_View()
 }
 
 
+/** 
+ \brief Return the current filename for the text in the buffer.
+
+ Fl_Help_View remains the owner of the allocated memory. If the filename
+ chages, the returned pointer will become stale. 
+
+ \return nullptr if the filename is empty
+ */
+const char *Fl_Help_View::filename() const { 
+  if (filename_[0]) 
+    return (filename_);
+  else 
+    return nullptr; 
+}
+
+
+/** 
+ \brief Return the current directory for the text in the buffer.
+
+ Fl_Help_View remains the owner of the allocated memory. If the directory
+ chages, the returned pointer will become stale. 
+
+ \return nullptr if the directory name is empty
+ */
+const char *Fl_Help_View::directory() const { 
+  if (directory_[0]) 
+    return (directory_);
+  else 
+    return nullptr; 
+}
+
+
+/**
+ \brief Set a callback function for following links.
+
+ This method assigns a callback function to use when a link is
+ followed or a file is loaded (via Fl_Help_View::load()) that
+ requires a different file or path.
+
+ The callback function receives a pointer to the Fl_Help_View
+ widget and the URI or full pathname for the file in question.
+ It must return a pathname that can be opened as a local file or NULL:
+
+ \code
+ const char *fn(Fl_Widget *w, const char *uri);
+ \endcode
+
+ The link function can be used to retrieve remote or virtual
+ documents, returning a temporary file that contains the actual
+ data. If the link function returns NULL, the value of
+ the Fl_Help_View widget will remain unchanged.
+
+ If the link callback cannot handle the URI scheme, it should
+ return the uri value unchanged or set the value() of the widget
+ before returning NULL.
+
+ \param[in] fn Pointer to the callback function
+*/
+void Fl_Help_View::link(Fl_Help_Func *fn) { 
+  link_ = fn; 
+}
+
 /** Loads the specified file.
 
  This method loads the specified file or URL. The filename may end in a
@@ -3403,17 +3468,13 @@ int Fl_Help_View::load(const char *f)
 }
 
 
-/** Resizes the help widget. */
-
-void
-Fl_Help_View::resize(int xx,    // I - New left position
-                     int yy,    // I - New top position
-                     int ww,    // I - New width
-                     int hh)    // I - New height
+/** 
+ \brief Override the superclass's resize method.
+ \param[in] xx, yy, ww, hh New position and size of the widget
+ */
+void Fl_Help_View::resize(int xx, int yy, int ww, int hh)
 {
-  Fl_Boxtype            b = box() ? box() : FL_DOWN_BOX;
-                                        // Box to draw...
-
+  Fl_Boxtype b = box() ? box() : FL_DOWN_BOX; // Box to draw...
 
   Fl_Widget::resize(xx, yy, ww, hh);
 
@@ -3423,24 +3484,24 @@ Fl_Help_View::resize(int xx,    // I - New left position
   hscrollbar_.resize(x() + Fl::box_dx(b),
                      y() + h() - scrollsize - Fl::box_dh(b) + Fl::box_dy(b),
                      w() - scrollsize - Fl::box_dw(b), scrollsize);
-
   format();
 }
 
 
-/** Scrolls the text to the indicated position, given a named destination.
-
-  \param[in] n target name
+/** 
+ \brief Scroll the text to the given anchor.
+ \param[in] anchor scroll to this named anchor
 */
 void
-Fl_Help_View::topline(const char *n)    // I - Target name
+Fl_Help_View::topline(const char *anchor)    // I - Target name
 {
-  std::string target_name = to_lower(n); // Convert to lower case
+  std::string target_name = to_lower(anchor); // Convert to lower case
   auto tl = target_line_map_.find(target_name);
   if (tl != target_line_map_.end()) {
     // Found the target name, scroll to the line
     topline(tl->second);
   } else {
+    // Scroll to the top.
     topline(0);
   }
 }