[skip ci] Cleanup file copyright comments, add file description.

Add code comments for grib plugin.
Hakansv · Dec 29, 2024 · 44774be · 44774be
1 parent e9a6c87
commit 44774be
Show file tree

Hide file tree

Showing 52 changed files with 1,440 additions and 423 deletions.
diff --git a/plugins/grib_pi/src/CursorData.cpp b/plugins/grib_pi/src/CursorData.cpp
@@ -1,11 +1,5 @@
-/******************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  GRIB Object
- * Author:   David Register
- *
- ***************************************************************************
- *   Copyright (C) 2010 by David S. Register   *
+/***************************************************************************
+ *   Copyright (C) 2010 by David S. Register                               *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
  *   it under the terms of the GNU General Public License as published by  *
@@ -21,10 +15,11 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
- *
+ ***************************************************************************/
+/**
+ * \file
+ * \implements \ref  CursorData.h
  */
-
 #include "pi_gl.h"
 #include "grib_pi.h"
 

diff --git a/plugins/grib_pi/src/CursorData.h b/plugins/grib_pi/src/CursorData.h
@@ -1,10 +1,4 @@
-/******************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  GRIB Plugin Friends
- * Author:   David Register
- *
- ***************************************************************************
+/***************************************************************************
  *   Copyright (C) 2010 by David S. Register   *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -22,9 +16,15 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
+ ***************************************************************************/
+/**
+ * \file
+ * GRIB Cursor Data Tracking and Display.
+ *
+ * Defines classes for tracking and displaying GRIB weather data at the cursor
+ * position on the chart. Provides real-time updates of meteorological
+ * parameters as the cursor moves.
  */
-
 #ifndef __GRIBUICData_H__
 #define __GRIBUICData_H__
 
@@ -41,9 +41,14 @@
 class GRIBUICtrlBar;
 class GribGrabberWin;
 class GribSpacerWin;
-//----------------------------------------------------------------------------------------------------------
-//    GRIB CtrlBar Specification
-//----------------------------------------------------------------------------------------------------------
+
+/**
+ * Tracks and displays GRIB meteorological data at cursor position.
+ *
+ * Display various meteorological parameters (wind, pressure, waves, etc.) at
+ * the current cursor position on the chart. Manages data display controls and
+ * handles user interactions for display preferences.
+ */
 class CursorData : public CursorDataBase {
 public:
   CursorData(wxWindow *window, GRIBUICtrlBar &parent);

diff --git a/plugins/grib_pi/src/CustomGrid.cpp b/plugins/grib_pi/src/CustomGrid.cpp
@@ -1,10 +1,4 @@
-/************************************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  personalized GRID
- * Author:   David Register
- *
- ***************************************************************************
+/***************************************************************************
  *   Copyright (C) 2010 by David S. Register   *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -21,10 +15,11 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
- *
+ ***************************************************************************/
+/**
+ * \file
+ * \implements \ref CustomGrid.h
  */
-
 #include "CustomGrid.h"
 
 #include <wx/graphics.h>

diff --git a/plugins/grib_pi/src/CustomGrid.h b/plugins/grib_pi/src/CustomGrid.h
@@ -1,10 +1,4 @@
-/******************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  personalized GRID
- * Author:   David Register
- *
- ***************************************************************************
+/***************************************************************************
  *   Copyright (C) 2010 by David S. Register   *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -21,7 +15,28 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
+ ***************************************************************************/
+/**
+ * \file
+ * Specialized Grid Control for GRIB Data Display.
+ *
+ * Implements a customized grid control optimized for displaying meteorological
+ * data with:
+ * - Direction arrows for vector quantities (wind, current, waves)
+ * - Numerical formatting for different parameter types
+ * - Custom cell rendering and column headers
+ * - Scrolling and viewport management
+ * - Row/column label handling
+ *
+ * Features:
+ * - Efficient cell visibility detection and rendering
+ * - Direction arrow rendering with custom geometry
+ * - Numerical value formatting and alignment
+ * - Platform-specific optimizations
+ * - Event handling for user interaction
+ *
+ * The grid is designed to efficiently handle large weather datasets while
+ * providing intuitive visualization of both scalar and vector quantities.
  */
 #ifndef __CUSTOMGRID_H__
 #define __CUSTOMGRID_H__

diff --git a/plugins/grib_pi/src/GrabberWin.cpp b/plugins/grib_pi/src/GrabberWin.cpp
@@ -1,10 +1,4 @@
-/******************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  GRIB Object
- * Author:   David Register
- *
- ***************************************************************************
+/***************************************************************************
  *   Copyright (C) 2010 by David S. Register   *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -21,10 +15,11 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
- *
+ ***************************************************************************/
+/**
+ * \file
+ * \implements \ref GrabberWin.h
  */
-
 #include "wx/wx.h"
 
 #include "folder.xpm"
@@ -39,7 +34,7 @@ EVT_MOUSE_EVENTS(GribGrabberWin::OnMouseEvent)
 EVT_PAINT(GribGrabberWin::OnPaint)
 END_EVENT_TABLE()
 
-    GribGrabberWin::GribGrabberWin(wxWindow* parent) {
+GribGrabberWin::GribGrabberWin(wxWindow* parent) {
   Create(parent);
 
   m_bLeftDown = false;

diff --git a/plugins/grib_pi/src/GrabberWin.h b/plugins/grib_pi/src/GrabberWin.h
@@ -1,10 +1,4 @@
-/******************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  GRIB Plugin Friends
- * Author:   David Register
- *
- ***************************************************************************
+/***************************************************************************
  *   Copyright (C) 2010 by David S. Register   *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -21,9 +15,27 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
+ ***************************************************************************/
+/**
+ * \file
+ * GRIB Dialog Grabber Control Interface.
+ *
+ * Implements a custom window control for manipulating GRIB dialog positioning
+ * and behavior:
+ * - Provides drag handle for repositioning dialogs
+ * - Manages window attachment and docking
+ * - Handles mouse interaction for window control
+ * - Supports custom bitmap rendering for visual feedback
+ *
+ * Features:
+ * - Custom paint handling for grabber visuals
+ * - Mouse event processing for drag operations
+ * - Automatic sizing and positioning
+ * - Platform-independent window management
+ *
+ * This component enables flexible positioning of GRIB data display windows
+ * within the OpenCPN interface while maintaining a consistent user experience.
  */
-
 #ifndef __GRIBGRABBERWIN_H__
 #define __GRIBGRABBERWIN_H__
 

diff --git a/plugins/grib_pi/src/GribOverlayFactory.cpp b/plugins/grib_pi/src/GribOverlayFactory.cpp
@@ -1,10 +1,4 @@
-/******************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  GRIB Object
- * Author:   David Register
- *
- ***************************************************************************
+/***************************************************************************
  *   Copyright (C) 2014 by David S. Register                               *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -21,10 +15,11 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
- *
+ ***************************************************************************/
+/**
+ * \file
+ * \implements \ref GribOverlayFactory.h
  */
-
 #include "wx/wxprec.h"
 
 #ifndef WX_PRECOMP

diff --git a/plugins/grib_pi/src/GribOverlayFactory.h b/plugins/grib_pi/src/GribOverlayFactory.h
@@ -1,10 +1,4 @@
-/******************************************************************************
- *
- * Project:  OpenCPN
- * Purpose:  GRIB Plugin Freinds
- * Author:   David Register
- *
- ***************************************************************************
+/***************************************************************************
  *   Copyright (C) 2014 by David S. Register                               *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -21,9 +15,23 @@
  *   along with this program; if not, write to the                         *
  *   Free Software Foundation, Inc.,                                       *
  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,  USA.         *
- ***************************************************************************
+ ***************************************************************************/
+/**
+ * \file
+ * GRIB Data Visualization and Rendering Factory.
+ *
+ * Provides comprehensive visualization capabilities for GRIB weather data in
+ * OpenCPN, including:
+ * - Wind barbs and particle animations
+ * - Pressure isobars and directional arrows
+ * - Color-coded overlay maps for various parameters
+ * - Numerical data displays and labels
+ *
+ * The factory manages both OpenGL and bitmap-based rendering paths, handles
+ * resource allocation, and provides efficient caching of rendered elements.
+ * It serves as the central hub for converting raw GRIB data into meaningful
+ * visual representations for mariners.
  */
-
 #ifndef _GRIBOVERLAYFACTORY_H_
 #define _GRIBOVERLAYFACTORY_H_
 
@@ -36,10 +44,13 @@
 #include "pi_ocpndc.h"
 #include "pi_TexFont.h"
 
-//----------------------------------------------------------------------------------------------------------
-//    Grib Overlay Specification
-//----------------------------------------------------------------------------------------------------------
-
+/**
+ * Container for rendered GRIB data visualizations in texture or bitmap form.
+ *
+ * This class manages the rendered representation of GRIB weather data,
+ * supporting both OpenGL texture-based rendering and bitmap-based rendering. It
+ * handles resource allocation and cleanup for both rendering paths.
+ */
 class GribOverlay {
 public:
   GribOverlay(void) {
@@ -71,7 +82,14 @@ class GribOverlay {
 #define MAX_PARTICLE_HISTORY 8
 #include <vector>
 #include <list>
+/**
+ * Individual particle for wind/current animation.
+ *
+ * Represents a single particle in the animation system with position history
+ * and rendering attributes.
+ */
 struct Particle {
+  /** Duration this particle should exist in animation cycles. */
   int m_Duration;
 
   // history is a ringbuffer.. because so many particles are
@@ -84,6 +102,11 @@ struct Particle {
   } m_History[MAX_PARTICLE_HISTORY];
 };
 
+/**
+ * Manager for particle animation system.
+ *
+ * Handles collections of particles and their rendering data arrays.
+ */
 struct ParticleMap {
 public:
   ParticleMap(int settings)
@@ -139,14 +162,17 @@ class LineBuffer {
   std::list<float> buffer;
 };
 
-//----------------------------------------------------------------------------------------------------------
-//    Grib Overlay Factory Specification
-//----------------------------------------------------------------------------------------------------------
-
 class GRIBUICtrlBar;
 class GribRecord;
 class GribTimelineRecordSet;
 
+/**
+ * Factory class for creating and managing GRIB data visualizations.
+ *
+ * This class is responsible for rendering all GRIB weather data visualizations
+ * in OpenCPN. It handles multiple visualization types including wind barbs,
+ * isobars, particles, directional arrows, and numeric overlays.
+ */
 class GRIBOverlayFactory : public wxEvtHandler {
 public:
   GRIBOverlayFactory(GRIBUICtrlBar &dlg);

diff --git a/plugins/grib_pi/src/GribReader.cpp b/plugins/grib_pi/src/GribReader.cpp
@@ -15,7 +15,10 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ***********************************************************************/
-
+/**
+ * \file
+ * \implements \ref GribReader.h
+ */
 #include "wx/wxprec.h"
 
 #ifndef WX_PRECOMP