EventMonitor Doxygen documentation update

EventMonitor/App.h

@@ -19,8 +19,10 @@
 */
 
 ///
-/// EventMonitor application
+/// \defgroup EventMonitor  Event Monitor
+/// Real-time log of application events
 ///
+
 class wxEventMonitorApp;
 
 #pragma once
@@ -32,6 +34,12 @@ class wxEventMonitorApp;
 #include <wx/intl.h>
 
 
+/// \addtogroup EventMonitor
+/// @{
+
+///
+/// EventMonitor application
+///
 class wxEventMonitorApp : public wxApp
 {
 public:
@@ -57,4 +65,6 @@ public:
     wxLocale             m_locale;  ///< Current locale
 };
 
+/// @}
+
 wxDECLARE_APP(wxEventMonitorApp);

EventMonitor/ETWLog.cpp

@@ -115,6 +115,8 @@ void wxEventTraceProcessorThread::Abort()
 }
 
 
+/// \cond internal
+
 wxThread::ExitCode wxEventTraceProcessorThread::Entry()
 {
     // Process events.
@@ -139,6 +141,8 @@ VOID WINAPI wxEventTraceProcessorThread::EventRecordCallback(_In_ PEVENT_RECORD
     _this->m_parent->QueueEvent(new wxETWEvent(wxEVT_ETW_EVENT, *pEvent));
 }
 
+/// \endcond
+
 
 //////////////////////////////////////////////////////////////////////////
 // wxETWListCtrl
@@ -460,6 +464,8 @@ void wxETWListCtrl::RebuildItems()
 }
 
 
+/// \cond internal
+
 bool wxETWListCtrl::IsVisible(const EVENT_RECORD &rec) const
 {
     return
@@ -561,7 +567,7 @@ wxString wxETWListCtrl::OnGetItemText(long item, long column) const
 }
 
 
-wxString wxETWListCtrl::OnGetItemText(const event_rec &rec, long column) const
+wxString wxETWListCtrl::OnGetItemText(const winstd::event_rec &rec, long column) const
 {
     switch (column) {
     case 0: {
@@ -678,6 +684,8 @@ void wxETWListCtrl::OnETWEvent(wxETWEvent& event)
     }
 }
 
+/// \endcond
+
 
 //////////////////////////////////////////////////////////////////////////
 // wxPersistentETWListCtrl

EventMonitor/ETWLog.h

@@ -20,32 +20,23 @@
 
 #include <wx/event.h>
 
+/// \addtogroup EventMonitor
+/// @{
+
 ///
 /// Maximum number of event records kept
 ///
 #define wxETWEVENT_RECORDS_MAX  1000000
 
-///
+/// @}
-/// ETW event
+
-///
 class wxETWEvent;
 wxDECLARE_EVENT(wxEVT_ETW_EVENT, wxETWEvent);
 #define wxETWEventHandler(func) wxEVENT_HANDLER_CAST(wxETWEventFunction, func)
 #define EVT_ETW_EVENT(func) wx__DECLARE_EVT0(wxEVT_ETW_EVENT, wxETWEventHandler(func))
 
-///
-/// Event trace processor
-///
 class wxEventTraceProcessorThread;
-
-///
-/// Event list control
-///
 class wxETWListCtrl;
-
-///
-/// Supports saving/restoring wxETWListCtrl state
-///
 class wxPersistentETWListCtrl;
 
 #pragma once
@@ -61,47 +52,106 @@ class wxPersistentETWListCtrl;
 #include <set>
 
 
+/// \addtogroup EventMonitor
+/// @{
+
+///
+/// ETW event
+///
 class wxETWEvent : public wxEvent
 {
 public:
+    ///
+    /// Creates ETW event
+    ///
+    /// \param[in] type    The unique type of event
+    /// \param[in] record  ETW event record
+    ///
     wxETWEvent(wxEventType type = wxEVT_NULL, const EVENT_RECORD &record = s_record_null);
+
+    ///
+    /// Copies an ETW event
+    ///
+    /// \param[in] event  ETW event to copy from
+    ///
     wxETWEvent(const wxETWEvent& event);
-    virtual wxEvent *Clone() const { return new wxETWEvent(*this); }
 
-    inline const winstd::event_rec&  GetRecord() const { return m_record; }
+    ///
-    inline       winstd::event_rec&  GetRecord()       { return m_record; }
+    /// Clones the ETW event
+    ///
+    /// \returns Event copy
+    ///
+    virtual wxEvent *Clone() const
+    {
+        return new wxETWEvent(*this);
+    }
 
-protected:
+    ///
-    bool DoSetExtendedData(size_t extended_data_count, const EVENT_HEADER_EXTENDED_DATA_ITEM *extended_data);
+    /// Returns ETW event record assosiated with event
-    bool DoSetUserData(size_t user_data_length, const void *user_data);
+    ///
+    inline const winstd::event_rec& GetRecord() const
+    {
+        return m_record;
+    }
+
+    ///
+    /// Returns ETW event record assosiated with event
+    ///
+    inline winstd::event_rec& GetRecord()
+    {
+        return m_record;
+    }
 
 private:
     DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxETWEvent)
 
 public:
-    static const EVENT_RECORD s_record_null;
+    static const EVENT_RECORD s_record_null; ///< Blank ETW event record
 
 protected:
     winstd::event_rec m_record; ///< ETW event record
 };
 
 
+///
+/// Prototype of the function consuming `wxETWEvent` events
+///
 typedef void (wxEvtHandler::*wxETWEventFunction)(wxETWEvent&);
 
 
+///
+/// Monitors ETW events and forwards them as `wxETWEvent` event
+///
 class wxEventTraceProcessorThread : public wxThread
 {
 public:
+    ///
+    /// A thread to process ETW events
+    ///
+    /// \param[in] parent    Event handler this thread will send record notifications
+    /// \param[in] sessions  An array of sessions to monitor
+    ///
     wxEventTraceProcessorThread(wxEvtHandler *parent, const wxArrayString &sessions);
+
+    ///
+    /// Destructor
+    ///
     virtual ~wxEventTraceProcessorThread();
 
+    ///
+    /// Closes all session handles to allow graceful thread termination
+    ///
     void Abort();
 
 protected:
+    /// \cond internal
     virtual ExitCode Entry();
+    /// \endcond
 
 private:
+    /// \cond internal
     static VOID WINAPI EventRecordCallback(PEVENT_RECORD pEvent);
+    /// \endcond
 
 protected:
     std::vector<TRACEHANDLE> m_traces;  ///< An array of tracing sessions this thread is monitoring
@@ -109,6 +159,9 @@ protected:
 };
 
 
+///
+/// Event list control
+///
 class wxETWListCtrl : public wxListCtrl
 {
 protected:
@@ -117,6 +170,9 @@ protected:
     ///
     struct less_guid : public std::binary_function<GUID, GUID, bool>
     {
+        ///
+        /// Compares two GUIDs
+        ///
         bool operator()(const GUID &a, const GUID &b) const
         {
             if (a.Data1 < b.Data1) return true;
@@ -136,6 +192,17 @@ protected:
     typedef std::set<GUID, less_guid> guidset;
 
 public:
+    ///
+    /// Creates a list control for ETW log display
+    ///
+    /// \param[in] parent     Parent window. Must not be \c NULL.
+    /// \param[in] id         Window identifier. The value \c wxID_ANY indicates a default value.
+    /// \param[in] pos        Window position. If \c wxDefaultPosition is specified then a default position is chosen.
+    /// \param[in] size       Window size. If \c wxDefaultSize is specified then the window is sized appropriately.
+    /// \param[in] style      Window style. See \c wxListCtrl.
+    /// \param[in] validator  Window validator
+    /// \param[in] name       Window name
+    ///
     wxETWListCtrl(
               wxWindow    *parent,
               wxWindowID  id         = wxID_ANY,
@@ -144,21 +211,70 @@ public:
               long        style      = wxLC_NO_SORT_HEADER|wxLC_REPORT|wxLC_VIRTUAL|wxNO_BORDER,
         const wxValidator &validator = wxDefaultValidator,
         const wxString    &name      = wxListCtrlNameStr);
+
+    ///
+    /// Destructor
+    ///
     virtual ~wxETWListCtrl();
 
-    inline bool IsEmpty() const { return m_rec_db.empty(); }
+    ///
+    /// Returns true if the list is empty
+    ///
+    inline bool IsEmpty() const
+    {
+        return m_rec_db.empty();
+    }
+
+    ///
+    /// Copies selected rows to clipboard
+    ///
     void CopySelected() const;
+
+    ///
+    /// Copies all rows (including hidden ones) to clipboard
+    ///
     void CopyAll() const;
+
+    ///
+    /// Empties the list
+    ///
     void ClearAll();
+
+    ///
+    /// Selects all rows
+    ///
     void SelectAll();
+
+    ///
+    /// Clears row selection
+    ///
     void SelectNone();
+
+    ///
+    /// Rebuilds the list
+    ///
     void RebuildItems();
 
+    ///
+    /// Checks if given ETW source is enabled
+    ///
+    /// \param[in] guid  GUID of ETW source
+    ///
+    /// \returns
+    /// - \c true if ETW source with \p guid GUID is enabled;
+    /// - \c false otherwise.
+    ///
     inline bool IsSourceEnabled(const GUID &guid) const
     {
         return m_sources.find(guid) != m_sources.end();
     }
 
+    ///
+    /// Enables/Disables ETW source
+    ///
+    /// \param[in] guid    GUID of ETW source
+    /// \param[in] enable  \c true to enable, \c false to disable
+    ///
     inline void EnableSource(const GUID &guid, bool enable = true)
     {
         auto s = m_sources.find(guid);
@@ -178,6 +294,7 @@ public:
     friend class wxPersistentETWListCtrl;   // Allow saving/restoring window state.
 
 protected:
+    /// \cond internal
     bool IsVisible(const EVENT_RECORD &rec) const;
     void FormatRow(const winstd::event_rec &rec, std::string &rowA, std::wstring &rowW) const;
     bool CopyToClipboard(const std::string &dataA, const std::wstring &dataW) const;
@@ -186,6 +303,8 @@ protected:
     virtual wxString OnGetItemText(long item, long column) const;
     virtual wxString OnGetItemText(const winstd::event_rec &rec, long column) const;
     void OnETWEvent(wxETWEvent& event);
+    /// \endcond
+
     DECLARE_EVENT_TABLE()
 
 public:
@@ -209,18 +328,48 @@ protected:
 };
 
 
+///
+/// Supports saving/restoring `wxETWListCtrl` state
+///
 class wxPersistentETWListCtrl : public wxPersistentWindow<wxETWListCtrl>
 {
 public:
+    ///
+    /// Constructor for a persistent window object
+    ///
+    /// \param[in] wnd  Window this object will save/restore
+    ///
     wxPersistentETWListCtrl(wxETWListCtrl *wnd);
 
+    ///
+    /// Returns the string uniquely identifying the objects supported by this adapter.
+    ///
+    /// \returns This implementation always returns `wxT(wxPERSIST_TLW_KIND)`
+    ///
     virtual wxString GetKind() const;
+
+    ///
+    /// Saves the object properties
+    ///
     virtual void Save() const;
+
+    ///
+    /// Restores the object properties
+    ///
+    /// \returns
+    /// - \c true if the properties were successfully restored;
+    /// - \c false otherwise.
+    ///
     virtual bool Restore();
 };
 
 
+///
+/// Creates persistent window object for `wxETWListCtrl` class window
+///
 inline wxPersistentObject *wxCreatePersistentObject(wxETWListCtrl *wnd)
 {
     return new wxPersistentETWListCtrl(wnd);
 }
+
+/// @}

EventMonitor/Frame.cpp

@@ -261,6 +261,8 @@ wxEventMonitorFrame::~wxEventMonitorFrame()
 }
 
 
+/// \cond internal
+
 void wxEventMonitorFrame::OnExit(wxCommandEvent& event)
 {
     Close();
@@ -408,6 +410,8 @@ void wxEventMonitorFrame::OnViewToolbar(wxCommandEvent& event)
     }
 }
 
+/// \endcond
+
 
 //////////////////////////////////////////////////////////////////////////
 // wxPersistentEventMonitorFrame

EventMonitor/Frame.h

@@ -18,14 +18,7 @@
     along with GÉANTLink. If not, see <http://www.gnu.org/licenses/>.
 */
 
-///
-/// EventMonitor main frame
-///
 class wxEventMonitorFrame;
-
-///
-/// Supports saving/restoring wxEventMonitorFrame GUI state
-///
 class wxPersistentEventMonitorFrame;
 
 #pragma once;
@@ -42,6 +35,12 @@ class wxPersistentEventMonitorFrame;
 #include <WinStd/Win.h>
 
 
+/// \addtogroup EventMonitor
+/// @{
+
+///
+/// EventMonitor main frame
+///
 class wxEventMonitorFrame : public wxFrame
 {
 protected:
@@ -62,12 +61,28 @@ protected:
     };
 
 public:
+    ///
+    /// Creates an EventMonitor frame window
+    ///
+    /// \param[in] parent  The window parent. This may be \c NULL. If it is non-NULL, the frame will always be displayed on top of the parent window on Windows.
+    /// \param[in] id      The window identifier. It may take a value of \c wxID_ANY to indicate a default value.
+    /// \param[in] title   The caption to be displayed on the frame's title bar.
+    /// \param[in] pos     The window position. The value \c wxDefaultPosition indicates a default position, chosen by either the windowing system or wxWidgets, depending on platform.
+    /// \param[in] size    The window size. The value \c wxDefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform.
+    /// \param[in] style   The window style. See `wxFrame` class description.
+    /// \param[in] name    The name of the window. This parameter is used to associate a name with the item, allowing the application user to set Motif resource values for individual windows.
+    ///
     wxEventMonitorFrame(wxWindow* parent, wxWindowID id = wxID_ANY, const wxString& title = _("Event Monitor"), const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxSize(600,400), long style = wxDEFAULT_FRAME_STYLE|wxTAB_TRAVERSAL, const wxString& name = wxT("EventMonitor"));
+
+    ///
+    /// Destructor
+    ///
     ~wxEventMonitorFrame();
 
     friend class wxPersistentEventMonitorFrame;
 
 protected:
+    /// \cond internal
     void OnExit(wxCommandEvent& event);
     void OnEditCopyUpdate(wxUpdateUIEvent& event);
     void OnEditCopy(wxCommandEvent& event);
@@ -87,8 +102,10 @@ protected:
     void OnViewLevel(wxCommandEvent& event);
     void OnViewToolbarUpdate(wxUpdateUIEvent& event);
     void OnViewToolbar(wxCommandEvent& event);
+    /// \endcond
 
 protected:
+    /// \cond internal
     wxMenuBar* m_menubar;
     wxMenu* m_menuProgram;
     wxMenu* m_menuEdit;
@@ -114,20 +131,45 @@ protected:
     wxStatusBar* m_statusBar;
     wxEventMonitorLogPanel* m_panel;
     wxAuiManager m_mgr;
+    /// \endcond
 };
 
 
+///
+/// Supports saving/restoring `wxEventMonitorFrame` GUI state
+///
 class wxPersistentEventMonitorFrame : public wxPersistentTLW
 {
 public:
+    ///
+    /// Constructor for a persistent window object
+    ///
+    /// \param[in] wnd  Window this object will save/restore
+    ///
     wxPersistentEventMonitorFrame(wxEventMonitorFrame *wnd);
 
+    ///
+    /// Saves the object properties
+    ///
     virtual void Save() const;
+
+    ///
+    /// Restores the object properties
+    ///
+    /// \returns
+    /// - \c true if the properties were successfully restored;
+    /// - \c false otherwise.
+    ///
     virtual bool Restore();
 };
 
 
+///
+/// Creates persistent window object for `wxETWListCtrl` class window
+///
 inline wxPersistentObject *wxCreatePersistentObject(wxEventMonitorFrame *wnd)
 {
     return new wxPersistentEventMonitorFrame(wnd);
 }
+
+/// @}

EventMonitor/LogPanel.h

@@ -18,14 +18,7 @@
     along with GÉANTLink. If not, see <http://www.gnu.org/licenses/>.
 */
 
-///
-/// EventMonitor trace log panel
-///
 class wxEventMonitorLogPanel;
-
-///
-/// Supports saving/restoring wxEventMonitorLogPanel state
-///
 class wxPersistentEventMonitorLogPanel;
 
 #pragma once
@@ -34,27 +27,68 @@ class wxPersistentEventMonitorLogPanel;
 #include <wx/persist/window.h>
 
 
+/// \addtogroup EventMonitor
+/// @{
+
+///
+/// EventMonitor trace log panel
+///
 class wxEventMonitorLogPanel : public wxEventMonitorLogPanelBase
 {
 public:
+    ///
+    /// Constructs EventMonitor log panel
+    ///
+    /// \param[in] parent  Parent window. Must not be \c NULL.
+    ///
     wxEventMonitorLogPanel(wxWindow* parent);
 
     friend class wxPersistentEventMonitorLogPanel;   // Allow saving/restoring window state.
 };
 
 
+///
+/// Supports saving/restoring `wxEventMonitorLogPanel` state
+///
 class wxPersistentEventMonitorLogPanel : public wxPersistentWindow<wxEventMonitorLogPanel>
 {
 public:
+    ///
+    /// Constructor for a persistent window object
+    ///
+    /// \param[in] wnd  Window this object will save/restore
+    ///
     wxPersistentEventMonitorLogPanel(wxEventMonitorLogPanel *wnd);
 
+    ///
+    /// Returns the string uniquely identifying the objects supported by this adapter.
+    ///
+    /// \returns This implementation always returns `wxT(wxPERSIST_TLW_KIND)`
+    ///
     virtual wxString GetKind() const;
+
+    ///
+    /// Saves the object properties
+    ///
     virtual void Save() const;
+
+    ///
+    /// Restores the object properties
+    ///
+    /// \returns
+    /// - \c true if the properties were successfully restored;
+    /// - \c false otherwise.
+    ///
     virtual bool Restore();
 };
 
 
+///
+/// Creates persistent window object for `wxEventMonitorLogPanel` class window
+///
 inline wxPersistentObject *wxCreatePersistentObject(wxEventMonitorLogPanel *wnd)
 {
     return new wxPersistentEventMonitorLogPanel(wnd);
 }
+
+/// @}

lib/PAP/include/Config.h

@@ -39,6 +39,12 @@ namespace eap
 
 namespace eap
 {
+    /// \addtogroup EAPBaseConfig
+    /// @{
+
+    ///
+    /// PAP configuration
+    ///
     class config_method_pap : public config_method_with_cred
     {
     public: