A file comment description block, which describes this file. It is pretty straightforward. These comments are structured and in Doxygen format. They are collected by Doxygen and make the generated documentation automatically.
//----------------------------------------------------------------------------------------
/*!
    \file       bookmark_dialog.h        
    \modified                            
    \copyright  (c) Robert O'Connor ( rob@medicalmnemonics.com )    
    \licence    GPL
    \brief      Describes bookmark_dialog class    
    \author     Robert O'Connor
    \date       2002/01/03    
 */  
// RCS-ID:      $Id: included_breakdown_h.html,v 1.2 2003/03/17 17:43:21 robertoconnor Exp $
//----------------------------------------------------------------------------------------
This is the regular C/C++ define that ensures the compiler will include the stuff in this .h header file only once, over the course of the compilation. It is of the format shown: this header file's filename in all capitals, with .h replaced as _H, with underscores at each end.
//----------------------------------------------------------------------------------------
// Begin single inclusion of this .h file condition
//----------------------------------------------------------------------------------------

#ifndef _BOOKMARK_DIALOG_H_
#define _BOOKMARK_DIALOG_H_
The GCC #pragma interface is required for proper Linux compilation. It is the name of this header file. If it wasn't put in, then every .cpp file would contain debug info about every other .cpp file, which makes code size, compilation time, etc, all worse. This directive tells compiler not to put the debug info in every .cpp file, just wait for bookmark_dialog.cpp and it will only be put in bookmark_dialog.cpp. We turn it off though for Apple, since OSX Jaguar doesn't like it (or need it).
//----------------------------------------------------------------------------------------
// GCC interface
//----------------------------------------------------------------------------------------

#if  defined(__GNUG__) && ! defined(__APPLE__)
    #pragma interface "bookmark_dialog.h"
#endif
This includes all the defines used by the program. The plucker_defines.h also includes a link to the program's setup.h file, which allows features to be easily compiled out of the program.
//----------------------------------------------------------------------------------------
// Shared defines
//----------------------------------------------------------------------------------------

#include "plucker_defines.h"
The program's setup.h file has a list of defines that allow a feature to be compiled out, by setting a feature define to 1 or 0. This file (bookmark_dialog) is part of the integrated HTML editor feature, so we want only want to include the rest of this file if setupUSE_INTEGRATED_HTML_EDITOR was set to 1 in the setup.h
//----------------------------------------------------------------------------------------
// Begin feature removal condition
//----------------------------------------------------------------------------------------

#if ( setupUSE_INTEGRATED_HTML_EDITOR )
Include whatever headers are needed by the class definition. Since bookmark dialog derives from wxWindow's wxDialog, we need to include the header of that file.
// ---------------------------------------------------------------------------------------
// Headers
// ---------------------------------------------------------------------------------------

#include "wx/dialog.h"
The class definition block: body dialog dervies from wxDialog. Note the Doxygen comments, which will document this class in the developer documentation.
//----------------------------------------------------------------------------------------
// Class definition: bookmark_dialog
//----------------------------------------------------------------------------------------

//! A dialog for a "a name=" tag for the HTML editor.
class bookmark_dialog : public wxDialog
{
This is a wxWindows DYNAMIC_CLASS macro used by the C++ concept of 'RTTI', which you may see in some classes. All you need know about RTTI or this macro is three things:
- It is pretty much required if this class that will be a component in another class. For example the main_listctrl gets made and embedded into the main_frame, and so the main_listctrl needs this macro.
- It is helpful in memory leak detection (for example Borland BCC would say 'Memory leak: bookmark dialog on line 54' on shutdown, and you could see what kind of object it was that you leaked).
-If this class is a class that your object can make and use at runtime, then DECLARE_DYNAMIC_CLASS(...) is the one to use. If it an abstract base class (such as plucker_wizard_base), then DECLARE_ABSTRACT_CLASS(..) is the one to use.
    DECLARE_DYNAMIC_CLASS( bookmark_dialog )
The public methods of the class. These are the functions that can be called by other classes. There will usually be a constructor, and destructor here, and perhaps a few more custom functions.
public:
First public method listed is the constructor. If you are using DECLARE_DYNAMIC_CLASS macro,  then you either need to supply a default argument for every parameter, or else have a second empty constructor that is just a dummy and isn't used.
    //! Constructor.
    /*!
        \param parent The parent window.
     */
    bookmark_dialog( wxWindow* parent = (wxWindow* )NULL );
After the constructor(s), comes the destructor. If planned to derive again from this class then this destructor would need to be virtual, so all the destructors get called, all the way back up the object hierarchy, not just one destructor.
    //!Destructor.
    virtual ~bookmark_dialog();   
After the constructor(s) and the destructor comes any other public methods
    //! Gets the tag strings generated by the dialog, ready to insert by parent
    /*!
        \param starting_text The text to place at the start of parent's selected text.private: 
        \param ending_text The text to place at the end of parent's selected text.  
     */
    void transfer_to( wxString& starting_text,
                      wxString& ending_text
                    );
Then comes a list of protected methods/members. Protected members are only availalble to this class, or any class that you later derive from this class.
protected:
Finally, the list of private members. Private members are only available to this class. They describe the internal workings of how this dialog manages itself, to get things done. Note that the private objects and pointers have a prefix of m_ to denote they are 'm'embers of this class.
private:
    void on_help_button( wxCommandEvent &event );  
    //Override base class functions
    void OnOK( wxCommandEvent& event );
    
    wxString m_starting_text;
    wxString m_ending_text;
This is a wxWindows macro that is required if you want the class to have some custom responses to any events. This will be seen in almost all GUI classes.
    DECLARE_EVENT_TABLE()

};
If this header file had a setup option all removal, then close that compiler #if condition.
//----------------------------------------------------------------------------------------
// End feature removal condition
//----------------------------------------------------------------------------------------

#endif // setupUSE_INTEGRATED_HTML_EDITOR 
An finally close up the compiler #if option that ensured this header only gets included once.
//----------------------------------------------------------------------------------------
// End single inclusion of this .h file condition
//----------------------------------------------------------------------------------------

#endif  //_BOOKMARK_DIALOG_H_