More schematic component object encapsulation and Doxygen comment warning fixes.

.bzrignore

@@ -5,6 +5,7 @@ eeschema/cmp_library_lexer.h
 eeschema/cmp_library_keywords.*
 eeschema/template_fieldnames_keywords.*
 eeschema/template_fieldnames_lexer.h
+new/html
 pcbnew/dialogs/dialog_freeroute_exchange_help_html.h
 Makefile
 CMakeFiles

CHANGELOG.txt

@@ -4,6 +4,15 @@ KiCad ChangeLog 2010
 Please add newer entries at the top, list the date and your name with
 email address.
 
+2010-dec-13 UPDATE Wayne Stambaugh <stambaughw@verizon.net>
+================================================================================
+  * Remove deprecated options and quoted project name option in Doxygen file.
+  * Make Bazaar ignore the files generated by Doxygen in the new folder.
+++EESchema
+  * More schematic component encapsulation work.
+  * Doxygen comment fixes.
+
+
 2010-Dec-13 UPDATE Dick Hollenbeck <dick@softplc.com>
 ================================================================================
 ++eeschema:

Doxyfile

@@ -4,7 +4,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = KiCad PCB EDA Suite
+PROJECT_NAME           = "KiCad PCB EDA Suite"
 PROJECT_NUMBER         =
 OUTPUT_DIRECTORY       = Documentation/doxygen
 CREATE_SUBDIRS         = NO
@@ -21,13 +21,11 @@ SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = YES
 QT_AUTOBRIEF           = NO
 MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = YES
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 4
 ALIASES                =
 OPTIMIZE_OUTPUT_FOR_C  = NO
-OPTIMIZE_OUTPUT_FOR_CPP = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 BUILTIN_STL_SUPPORT    = NO
 CPP_CLI_SUPPORT        = NO

eeschema/block.cpp

@@ -883,7 +883,7 @@ static LIB_PIN* GetNextPinPosition( SCH_COMPONENT* aDrawLibItem,
         Multi       = aDrawLibItem->GetUnit();
         convert     = aDrawLibItem->GetConvert();
         CmpPosition = aDrawLibItem->m_Pos;
-        transform   = aDrawLibItem->m_Transform;
+        transform   = aDrawLibItem->GetTransform();
     }
     else
         Pin = Entry->GetNextPin( Pin );

eeschema/dangling_ends.cpp

@@ -76,7 +76,7 @@ LIB_PIN* SCH_EDIT_FRAME::LocatePinEnd( SCH_ITEM* DrawList, const wxPoint& pos )
                                 // and in schematic Y axis is top to bottom
 
     else                        // calculate the pin position in schematic
-        pinpos = DrawLibItem->m_Transform.TransformCoordinate( pinpos ) + DrawLibItem->m_Pos;
+        pinpos = DrawLibItem->GetTransform().TransformCoordinate( pinpos ) + DrawLibItem->m_Pos;
 
     if( pos == pinpos )
         return Pin;

eeschema/edit_component_in_schematic.cpp

@@ -53,10 +53,10 @@ void SCH_EDIT_FRAME::StartMoveCmpField( SCH_FIELD* aField, wxDC* DC )
     // under some circumstances, but that inversion is not preserved by all
     // combinations of mirroring and rotation.  The following clause is true
     // when the number of rotations and the number of mirrorings are both odd.
-    if( comp->m_Transform.x2 * comp->m_Transform.y1 < 0 )
+    if( comp->GetTransform().x2 * comp->GetTransform().y1 < 0 )
         NEGATE( newpos.y );
 
-    newpos = comp->m_Transform.TransformCoordinate( newpos ) + pos;
+    newpos = comp->GetTransform().TransformCoordinate( newpos ) + pos;
 
     DrawPanel->CursorOff( DC );
     GetScreen()->m_Curseur = newpos;
@@ -209,7 +209,7 @@ static void MoveCmpField( WinEDA_DrawPanel* panel, wxDC* DC, bool erase )
     /* Positions are calculated by the transpose matrix,  Rotating mirror. */
     wxPoint pt( panel->GetScreen()->m_Curseur - pos );
 
-    currentField->m_Pos = pos + component->m_Transform.TransformCoordinate( pt );
+    currentField->m_Pos = pos + component->GetTransform().TransformCoordinate( pt );
 
     currentField->Draw( panel, DC, wxPoint( 0, 0 ), g_XorMode );
 }

eeschema/find.cpp

@@ -190,7 +190,7 @@ SCH_ITEM* SCH_EDIT_FRAME::FindComponentAndItem( const wxString& component_refere
         }
         wxPoint delta;
         pos  -= Component->m_Pos;
-        delta = Component->m_Transform.TransformCoordinate( pos );
+        delta = Component->GetTransform().TransformCoordinate( pos );
         pos   = delta + Component->m_Pos;
 
         wxPoint old_cursor_position    = sheet->LastScreen()->m_Curseur;

eeschema/getpart.cpp

@@ -300,7 +300,7 @@ static void ExitPlaceCmp( WinEDA_DrawPanel* Panel, wxDC* DC )
     {
         wxPoint move_vector = OldPos - Component->m_Pos;
         Component->Move( move_vector );
-        Component->m_Transform = OldTransform;
+        Component->SetTransform( OldTransform );
         Component->m_Flags = 0;
     }
 
@@ -431,7 +431,7 @@ void SCH_EDIT_FRAME::StartMovePart( SCH_COMPONENT* Component, wxDC* DC )
     DrawPanel->ForceCloseManageCurseur = ExitPlaceCmp;
     GetScreen()->SetCurItem( Component );
     OldPos = Component->m_Pos;
-    OldTransform = Component->m_Transform;
+    OldTransform = Component->GetTransform();
 
 #if 1
 

eeschema/hierarch.cpp

@@ -168,7 +168,7 @@ WinEDA_HierFrame::~WinEDA_HierFrame()
 }
 
 
-void WinEDA_HierFrame::OnQuit( wxCommandEvent& WXUNUSED (event) )
+void WinEDA_HierFrame::OnQuit( wxCommandEvent& event )
 {
     // true is to force the frame to close
     Close( true );

eeschema/libeditframe.h

@@ -114,7 +114,7 @@ public:
      * <p>
      * EVT_CLOSE( LIB_EDIT_FRAME::OnCloseWindow )
      */
-    void CloseWindow( wxCommandEvent& WXUNUSED(event) )
+    void CloseWindow( wxCommandEvent& event )
     {
         // Generate a wxCloseEvent
         Close( false );

eeschema/netlist.cpp

@@ -641,7 +641,9 @@ static void AddConnectedObjects( SCH_SHEET_PATH*               sheetlist,
                 if( pin->GetConvert() && ( pin->GetConvert() != DrawLibItem->GetConvert() ) )
                     continue;
 
-                wxPoint pos2 = DrawLibItem->m_Transform.TransformCoordinate( pin->GetPosition() ) +
+                wxPoint pos2;
+
+                pos2 = DrawLibItem->GetTransform().TransformCoordinate( pin->GetPosition() ) +
                     DrawLibItem->m_Pos;
 
                 new_item = new NETLIST_OBJECT();

eeschema/plot.cpp

@@ -51,7 +51,7 @@ static void PlotLibPart( PLOTTER* plotter, SCH_COMPONENT* DrawLibItem )
     if( Entry == NULL )
         return;;
 
-    temp = DrawLibItem->m_Transform;
+    temp = DrawLibItem->GetTransform();
 
     Entry->Plot( plotter, DrawLibItem->GetUnit(), DrawLibItem->GetConvert(),
                  DrawLibItem->m_Pos, temp );
@@ -90,7 +90,7 @@ static void PlotTextField( PLOTTER* plotter, SCH_COMPONENT* DrawLibItem,
     /* Calculate the text orientation, according to the component
      * orientation/mirror */
     int orient = field->m_Orient;
-    if( DrawLibItem->m_Transform.y1 )  // Rotate component 90 deg.
+    if( DrawLibItem->GetTransform().y1 )  // Rotate component 90 deg.
     {
         if( orient == TEXT_ORIENT_HORIZ )
             orient = TEXT_ORIENT_VERT;

eeschema/sch_component.h

@@ -48,26 +48,17 @@ class SCH_COMPONENT : public SCH_ITEM
 {
     friend class DIALOG_EDIT_COMPONENT_IN_SCHEMATIC;
 
-    wxString m_ChipName;  ///< Name to look for in the library, i.e. "74LS00".
-    int      m_unit;      ///< The unit for multiple part per package components.
-    int      m_convert;   ///< The alternate body style for components that have more than
-                          ///< one body style defined.  Primarily used for components that
-                          ///< have a De Morgan conversion.
-    wxString m_prefix;    ///< C, R, U, Q etc - the first character which typically indicates
-                          ///< what the component is. Determined, upon placement, from the
-                          ///< library component.  Created upon file load, by the first
-                          ///<  non-digits in the reference fields.
-
-public:
-    wxPoint  m_Pos;
-
-    TRANSFORM m_Transform;            /* The rotation/mirror transformation
-                                       * matrix. */
-
-private:
-
-    SCH_FIELDS m_Fields;              ///< variable length list of fields
-
+    wxString m_ChipName;    ///< Name to look for in the library, i.e. "74LS00".
+    int      m_unit;        ///< The unit for multiple part per package components.
+    int      m_convert;     ///< The alternate body style for components that have more than
+                            ///< one body style defined.  Primarily used for components that
+                            ///< have a De Morgan conversion.
+    wxString m_prefix;      ///< C, R, U, Q etc - the first character which typically indicates
+                            ///< what the component is. Determined, upon placement, from the
+                            ///< library component.  Created upon file load, by the first
+                            ///<  non-digits in the reference fields.
+    TRANSFORM m_transform;  ///< The rotation/mirror transformation matrix.
+    SCH_FIELDS m_Fields;    ///< Variable length list of fields.
 
     /* Hierarchical references.
      * format is
@@ -80,6 +71,11 @@ private:
      */
     wxArrayString m_PathsAndReferences;
 
+public:
+    wxPoint  m_Pos;
+
+private:
+
     void Init( const wxPoint& pos = wxPoint( 0, 0 ) );
 
     EDA_Rect GetBodyBoundingBox() const;
@@ -135,12 +131,13 @@ public:
 
     wxString GetPrefix() const { return m_prefix; }
 
-    TRANSFORM& GetTransform() const { return const_cast< TRANSFORM& >( m_Transform ); }
+    TRANSFORM& GetTransform() const { return const_cast< TRANSFORM& >( m_transform ); }
+
+    void SetTransform( const TRANSFORM& aTransform );
 
     /**
      * Function Save
-     * writes the data structures for this object out to a FILE in "*.brd"
-     * format.
+     * writes the data structures for this object out to a FILE in "*.sch" format.
      * @param aFile The FILE to write to.
      * @return bool - true if success writing else false.
      */
@@ -149,16 +146,15 @@ public:
     /**
      * Load schematic component from \a aLine in a .sch file.
      *
-     * @param aLine - Essentially this is file to read the component from.
-     * @param aErrorMsg - Description of the error if an error occurs while loading the component.
+     * @param aLine Essentially this is file to read the component from.
+     * @param aErrorMsg Description of the error if an error occurs while loading the component.
      * @return True if the component loaded successfully.
      */
     virtual bool Load( LINE_READER& aLine, wxString& aErrorMsg );
 
     /**
      * Function GenCopy
-     * returns a copy of this object but with the linked list pointers
-     * set to NULL.
+     * returns a copy of this object but with the linked list pointers set to NULL.
      * @return SCH_COMPONENT* - a copy of me.
      */
     SCH_COMPONENT* GenCopy() const
@@ -166,6 +162,12 @@ public:
         return new SCH_COMPONENT( *this );
     }
 
+    /**
+     * Function SetOrientation
+     * computes the new transform matrix based on \a aOrientation for the component which is
+     * applied to the current transform.
+     * @param aOrientation The orientation to apply to the transform.
+     */
     void SetOrientation( int aOrientation );
 
     /**
@@ -184,11 +186,20 @@ public:
      */
     int        GetOrientation();
 
-    wxPoint    GetScreenCoord( const wxPoint& coord );
+    /**
+     * Function GetScreenCoord
+     * Returns the coordinated point relative to the orientation of the component of \a aPoint.
+     * The coordinates are always relative to the anchor position of the component.
+     * @param aPoint The coordinates to transform.
+     * @return The transformed point.
+     */
+    wxPoint    GetScreenCoord( const wxPoint& aPoint );
+
     void       DisplayInfo( WinEDA_DrawFrame* frame );
 
     /**
-     * Suppress annotation ( i.i IC23 changed to IC? and part reset to 1)
+     * Function ClearAnnotation
+     * clears exiting component annotation ( i.i IC23 changed to IC? and part reset to 1)
      * @param aSheet: SCH_SHEET_PATH value: if NULL remove all annotations,
      *             else remove annotation relative to this sheetpath
      */
@@ -196,27 +207,19 @@ public:
 
     /**
      * Function SetTimeStamp
-     * Change the old time stamp to the new time stamp.
-     * the time stamp is also modified in paths
+     * changes the time stamp to \a aNewTimeStamp updates the reference path.
+     * @see m_PathsAndReferences
      * @param aNewTimeStamp = new time stamp
      */
     void       SetTimeStamp( long aNewTimeStamp );
 
-    /**
-     * Function GetBoundaryBox
-     * returns the orthogonal, bounding box of this object for display purposes.
-     * This box should be an enclosing perimeter for graphic items and pins.
-     * this include only fields defined in library
-     * use GetBoundingBox() to include fields in schematic
-     */
-    EDA_Rect   GetBoundaryBox() const;
-
     /**
      * Function GetBoundingBox
-     * returns the orthogonal, bounding box of this object for display purposes.
-     * This box should be an enclosing perimeter for visible components of this
-     * object, and the units should be in the pcb or schematic coordinate system.
-     * It is OK to overestimate the size by a few counts.
+     * returns the bounding box of this object for display purposes. This box should be an
+     * enclosing perimeter for visible components of this object, and the units should be
+     * in the pcb or schematic coordinate system.  It is OK to overestimate the size by a
+     * few counts.
+     * @return The bounding rectangle of the component.
      */
     EDA_Rect   GetBoundingBox() const;
 
@@ -267,7 +270,8 @@ public:
     int GetFieldCount() const { return (int) m_Fields.size(); }
 
     /**
-     * Find a component pin by number.
+     * Function GetPin
+     * finds a component pin by number.
      *
      * @param number - The number of the pin to find.
      * @return Pin object if found, otherwise NULL.
@@ -326,34 +330,47 @@ public:
 
     // Geometric transforms (used in block operations):
 
-    /** virtual function Move
-     * move item to a new position.
-     * @param aMoveVector = the displacement vector
+    /**
+     * Function Move
+     * moves item to a new position by \a aMoveVector.
+     * @param aMoveVector The displacement to move the component
      */
     virtual void Move( const wxPoint& aMoveVector )
     {
+        if( aMoveVector == wxPoint( 0, 0 ) )
+            return;
+
         m_Pos += aMoveVector;
+
         for( int ii = 0; ii < GetFieldCount(); ii++ )
             GetField( ii )->Move( aMoveVector );
-    }
 
+        SetModified();
+    }
 
-    /** virtual function Mirror_Y
-     * mirror item relative to an Y axis
-     * @param aYaxis_position = the y axis position
+    /**
+     * Function Mirror_Y
+     * mirrors the component relative to an Y axis about the \a aYaxis_position.
+     * @param aYaxis_position The y axis position
      */
     virtual void Mirror_Y( int aYaxis_position );
+
+    /**
+     * Function Mirror_X (virtual)
+     * mirrors item relative to an X axis about the \a aXaxis_position.
+     * @param aXaxis_position The x axis position
+     */
     virtual void Mirror_X( int aXaxis_position );
-    virtual void Rotate( wxPoint rotationPoint );
 
+    virtual void Rotate( wxPoint rotationPoint );
 
     /**
-     * Compare schematic component reference and value fields against search string.
+     * Function Matches
+     * compares component reference and value fields against \a aSearchData.
      *
-     * @param aSearchData - Criteria to search against.
-     * @param aAuxData - a pointer on auxiliary data, if needed.
-     *        When searching string in REFERENCE field we must know the sheet path
-     *          This param is used in this case
+     * @param aSearchData Criteria to search against.
+     * @param aAuxData  Pointer to auxiliary data, if needed.
+     *        Used when searching string in REFERENCE field we must know the sheet path
      * @param aFindLocation - a wxPoint where to put the location of matched item. can be NULL.
      * @return True if this component reference or value field matches the search criteria.
      */

eeschema/sch_field.cpp

@@ -103,7 +103,7 @@ void SCH_FIELD::Draw( WinEDA_DrawPanel* panel, wxDC* DC,
     /* Calculate the text orientation, according to the component
      * orientation/mirror */
     orient = m_Orient;
-    if( parentComponent->m_Transform.y1 )  // Rotate component 90 degrees.
+    if( parentComponent->GetTransform().y1 )  // Rotate component 90 degrees.
     {
         if( orient == TEXT_ORIENT_HORIZ )
             orient = TEXT_ORIENT_VERT;
@@ -248,10 +248,10 @@ EDA_Rect SCH_FIELD::GetBoundingBox() const
     hjustify = m_HJustify;
     vjustify = m_VJustify;
 
-    pos2 = pos + parentComponent->m_Transform.TransformCoordinate( pos1 );
+    pos2 = pos + parentComponent->GetTransform().TransformCoordinate( pos1 );
 
     // Calculate the text orientation, according to the component orientation/mirror.
-    if( parentComponent->m_Transform.y1 )
+    if( parentComponent->GetTransform().y1 )
     {
         if( orient == TEXT_ORIENT_HORIZ )
             orient = TEXT_ORIENT_VERT;
@@ -260,23 +260,23 @@ EDA_Rect SCH_FIELD::GetBoundingBox() const
     }
 
     // Calculate the text justification, according to the component orientation/mirror.
-    if( parentComponent->m_Transform.y1 )
+    if( parentComponent->GetTransform().y1 )
     {
         /* is it mirrored (for text justify)*/
         EXCHG( hjustify, vjustify );
 
-        if( parentComponent->m_Transform.x2 < 0 )
+        if( parentComponent->GetTransform().x2 < 0 )
             NEGATE( vjustify );
 
-        if( parentComponent->m_Transform.y1 > 0 )
+        if( parentComponent->GetTransform().y1 > 0 )
             NEGATE( hjustify );
     }
     else    /* component horizontal: is it mirrored (for text justify)*/
     {
-        if( parentComponent->m_Transform.x1 < 0 )
+        if( parentComponent->GetTransform().x1 < 0 )
             NEGATE( hjustify );
 
-        if( parentComponent->m_Transform.y2 > 0 )
+        if( parentComponent->GetTransform().y2 > 0 )
             NEGATE( vjustify );
     }
 

eeschema/schematic_undo_redo.cpp

@@ -183,30 +183,6 @@ void SwapData( EDA_ITEM* aItem, EDA_ITEM* aImage )
 }
 
 
-/**
- * Function SaveCopyInUndoList
- * Create a copy of the current schematic item, and put it in the undo list.
- *
- *  flag_type_command =
- *      UR_CHANGED
- *      UR_NEW
- *      UR_DELETED
- *      UR_WIRE_IMAGE
- *      UR_MOVED
- *
- * If it is a delete command, items are put on list with the .Flags member
- * set to UR_DELETED.  When it will be really deleted, the GetDrawItems() and the
- * sub-hierarchy will be deleted.  If it is only a copy, the GetDrawItems() and the
- * sub-hierarchy must NOT be deleted.
- *
- * Note:
- * Edit wires and buses is a bit complex.
- * because when a new wire is added, modifications in wire list
- * (wire concatenation) there are modified items, deleted items and new items
- * so flag_type_command is UR_WIRE_IMAGE: the struct ItemToCopy is a list of
- * wires saved in Undo List (for Undo or Redo commands, saved wires will be
- * exchanged with current wire list
- */
 void SCH_EDIT_FRAME::SaveCopyInUndoList( SCH_ITEM*      aItem,
                                          UndoRedoOpType aCommandType,
                                          const wxPoint& aTransformPoint )
@@ -271,11 +247,6 @@ void SCH_EDIT_FRAME::SaveCopyInUndoList( SCH_ITEM*      aItem,
 }
 
 
-/**
- * Function SaveCopyInUndoList
- * @param aItemsList = a PICKED_ITEMS_LIST of items to save
- * @param aTypeCommand = type of command ( UR_CHANGED, UR_NEW, UR_DELETED ...
- */
 void SCH_EDIT_FRAME::SaveCopyInUndoList( PICKED_ITEMS_LIST& aItemsList,
                                          UndoRedoOpType     aTypeCommand,
                                          const wxPoint&     aTransformPoint )
@@ -344,14 +315,6 @@ void SCH_EDIT_FRAME::SaveCopyInUndoList( PICKED_ITEMS_LIST& aItemsList,
 }
 
 
-/**
- * Function PutDataInPreviousState
- * Used in undo or redo command.
- * Put data pointed by List in the previous state, i.e. the state memorized
- * by List
- * @param aList = a PICKED_ITEMS_LIST pointer to the list of items to undo/redo
- * @param aRedoCommand = a bool: true for redo, false for undo
- */
 void SCH_EDIT_FRAME::PutDataInPreviousState( PICKED_ITEMS_LIST* aList, bool aRedoCommand )
 {
     SCH_ITEM* item;
@@ -442,13 +405,6 @@ void SCH_EDIT_FRAME::PutDataInPreviousState( PICKED_ITEMS_LIST* aList, bool aRed
 }
 
 
-/**
- * Function GetSchematicFromUndoList
- *  Undo the last edition:
- *  - Save the current schematic in Redo list
- *  - Get the previous version of the schematic from undo list
- *  @return none
- */
 void SCH_EDIT_FRAME::GetSchematicFromUndoList( wxCommandEvent& event )
 {
     if( GetScreen()->GetUndoCommandCount() <= 0 )
@@ -464,7 +420,6 @@ void SCH_EDIT_FRAME::GetSchematicFromUndoList( wxCommandEvent& event )
     List->ReversePickersListOrder();
     GetScreen()->PushCommandToRedoList( List );
 
-//    m_drawItem = NULL;
     OnModify();
     SetSheetNumberAndCount();
     ReCreateHToolbar();
@@ -475,13 +430,6 @@ void SCH_EDIT_FRAME::GetSchematicFromUndoList( wxCommandEvent& event )
 }
 
 
-/**
- * Function GetSchematicFromRedoList
- * Redo the last edition:
- *  - Save the current schematic in undo list
- *  - Get the previous version from Redo list
- *  @return none
- */
 void SCH_EDIT_FRAME::GetSchematicFromRedoList( wxCommandEvent& event )
 {
     if( GetScreen()->GetRedoCommandCount() == 0 )
@@ -498,7 +446,6 @@ void SCH_EDIT_FRAME::GetSchematicFromRedoList( wxCommandEvent& event )
     List->ReversePickersListOrder();
     GetScreen()->PushCommandToUndoList( List );
 
-//    m_drawItem = NULL;
     OnModify();
     SetSheetNumberAndCount();
     ReCreateHToolbar();

eeschema/schframe.cpp

@@ -423,19 +423,6 @@ int SCH_EDIT_FRAME::BestZoom()
 }
 
 
-/**
- * Function GetUniqueFilenameForCurrentSheet
- * @return a filename that can be used in plot and print functions
- * for the current screen and sheet path.
- * This filename is unique and must be used insteed of the screen filename
- * (or sheet filename) when one must creates file for each sheet in the
- * heierarchy.
- * because in complex hierarchies a sheet and a SCH_SCREEN is used more than
- * once
- * Name is &ltroot sheet filename&gt-&ltsheet path&gt
- * and has no extension.
- * However if filename is too long name is &ltsheet filename&gt-&ltsheet number&gt
- */
 wxString SCH_EDIT_FRAME::GetUniqueFilenameForCurrentSheet()
 {
     wxFileName fn = g_RootSheet->GetFileName();

eeschema/transform.h

@@ -56,6 +56,8 @@ public:
 
     bool operator==( const TRANSFORM& aTransform ) const;
 
+    bool operator!=( const TRANSFORM& aTransform ) const { return !( *this == aTransform ); }
+
    /**
     * Calculate new coordinate according to the transform.
     *

include/wxEeschemaStruct.h

@@ -290,9 +290,8 @@ public:
      * (or screen filename) when one must creates file for each sheet in the
      * hierarchy.  because in complex hierarchies a sheet and a SCH_SCREEN is
      * used more than once
-     * Name is <root sheet filename>-<sheet path>
-     * and has no extension.
-     * However if filename is too long name is <sheet filename>-<sheet number>
+     * Name is &ltroot sheet filename&gt-&ltsheet path&gt and has no extension.
+     * However if filename is too long name is &ltsheet filename&gt-&ltsheet number&gt
      */
     wxString     GetUniqueFilenameForCurrentSheet();
 
@@ -304,8 +303,9 @@ public:
      */
     void         SetSheetNumberAndCount();
 
-    /** Virtual function PrintPage
-     * used to print a page
+    /**
+     * Function PrintPage
+     * is used to print a schematic page.
      * Print the page pointed by ActiveScreen, set by the calling print function
      * @param aDC = wxDC given by the calling print function
      * @param aPrint_Sheet_Ref = true to print page references
@@ -355,8 +355,7 @@ public:
     void            Save_File( wxCommandEvent& event );
     void            SaveProject();
     bool            LoadOneEEProject( const wxString& FileName, bool IsNew );
-    bool            LoadOneEEFile( SCH_SCREEN*     screen,
-                                   const wxString& FullFileName );
+    bool            LoadOneEEFile( SCH_SCREEN* screen, const wxString& FullFileName );
     bool            ReadInputStuffFile();
 
     /**
@@ -375,8 +374,7 @@ public:
      * @param aSetFieldsAttributeToVisible = true to set the footprint field flag to visible
      * @return bool - true if success, else true.
      */
-    bool            ProcessStuffFile( FILE* aFilename,
-                                      bool  aSetFieldsAttributeToVisible );
+    bool            ProcessStuffFile( FILE* aFilename, bool  aSetFieldsAttributeToVisible );
 
     bool            SaveEEFile( SCH_SCREEN* screen, int FileSave );
 
@@ -528,16 +526,35 @@ public:
 
     /**
      * Function SaveCopyInUndoList.
-     * Creates a new entry in undo list of commands.
-     * add a picker to handle aItemToCopy
+     * Create a copy of the current schematic item, and put it in the undo list.
+     *
+     *  flag_type_command =
+     *      UR_CHANGED
+     *      UR_NEW
+     *      UR_DELETED
+     *      UR_WIRE_IMAGE
+     *      UR_MOVED
+     *
+     * If it is a delete command, items are put on list with the .Flags member
+     * set to UR_DELETED.  When it will be really deleted, the GetDrawItems() and the
+     * sub-hierarchy will be deleted.  If it is only a copy, the GetDrawItems() and the
+     * sub-hierarchy must NOT be deleted.
+     *
+     * @Note
+     * Edit wires and buses is a bit complex.
+     * because when a new wire is added, modifications in wire list
+     * (wire concatenation) there are modified items, deleted items and new items
+     * so flag_type_command is UR_WIRE_IMAGE: the struct ItemToCopy is a list of
+     * wires saved in Undo List (for Undo or Redo commands, saved wires will be
+     * exchanged with current wire list
      * @param aItemToCopy = the schematic item modified by the command to undo
      * @param aTypeCommand = command type (see enum UndoRedoOpType)
      * @param aTransformPoint = the reference point of the transformation,
      *                          for commands like move
      */
     void SaveCopyInUndoList( SCH_ITEM* aItemToCopy,
-                            UndoRedoOpType aTypeCommand,
-                            const wxPoint& aTransformPoint = wxPoint( 0, 0 ) );
+                             UndoRedoOpType aTypeCommand,
+                             const wxPoint& aTransformPoint = wxPoint( 0, 0 ) );
 
     /**
      * Function SaveCopyInUndoList (overloaded).
@@ -549,21 +566,19 @@ public:
      *                          for commands like move
      */
     void SaveCopyInUndoList( PICKED_ITEMS_LIST& aItemsList,
-                            UndoRedoOpType aTypeCommand,
-                            const wxPoint& aTransformPoint = wxPoint( 0, 0 ) );
+                             UndoRedoOpType aTypeCommand,
+                             const wxPoint& aTransformPoint = wxPoint( 0, 0 ) );
 
 private:
 
     /**
      * Function PutDataInPreviousState
-     * Used in undo or redo command.
-     * Put data pointed by List in the previous state, i.e. the state
-     * memorized by List
-     * @param aList = a PICKED_ITEMS_LIST pointer to the list of items to
-     *                undo/redo
-     * @param aRedoCommand = a bool: true for redo, false for undo
+     * is used in undo or redo command to put data pointed by List in the previous state, i.e.
+     * the state stored in \a aList
+     * @param aList a PICKED_ITEMS_LIST pointer to the list of items to undo/redo
+     * @param aRedoCommand  a bool: true for redo, false for undo
      */
-    void     PutDataInPreviousState( PICKED_ITEMS_LIST* aList, bool aRedoCommand );
+    void PutDataInPreviousState( PICKED_ITEMS_LIST* aList, bool aRedoCommand );
 
     /**
      * Function GetSchematicFromRedoList
@@ -576,10 +591,9 @@ private:
 
     /**
      * Function GetSchematicFromUndoList
-     *  Undo the last edition:
+     * performs an undo the last edition:
      *  - Save the current schematic in Redo list
      *  - Get an old version of the schematic from Undo list
-     *  @return none
      */
     void     GetSchematicFromUndoList( wxCommandEvent& event );
 
@@ -602,7 +616,7 @@ public:
     virtual int  ReturnBlockCommand( int aKey );
 
     /**
-     * Function HandleBlockPlace( )
+     * Function HandleBlockPlace
      * Called after HandleBlockEnd, when a block command needs to be
      * executed after the block is moved to its new place
      * (bloc move, drag, copy .. )
@@ -611,7 +625,7 @@ public:
     virtual void HandleBlockPlace( wxDC* DC );
 
     /**
-     * Function HandleBlockEnd( )
+     * Function HandleBlockEnd
      * Handle the "end"  of a block command,
      * i.e. is called at the end of the definition of the area of a block.
      * depending on the current block command, this command is executed