Documentation and coding policy fixes.

* Fix all Doxygen warnings except polygon files.
* Add footprint library table tasks to TODO.txt.
* Add definition to drag.h to prevent nesting.
* Coding policy fixes.

Documentation/guidelines/UIpolicies.txt

@@ -5,8 +5,9 @@
 Capitalization:
 
     For any visible text used within KiCad, follow recommendations here:
-    http://library.gnome.org/devel/hig-book/2.20/design-text-labels.html.en#layout-capitalization
+    http://developer.gnome.org/hig-book/stable/design-text-labels.html.en
-    This applies to all Menus, Titles, Labels, Tooltips, Buttons, etc.
+    in the "Capitalization" section.  This applies to all Menus, Titles,
+    Labels, Tooltips, Buttons, etc.
 
     The capitalization for the application names is KiCad, Eeschema, CvPcb,
     GerbView, and Pcbnew.  All strings that have application names that are
@@ -19,7 +20,7 @@ Dialogs:
 
     Follow the recommendations here:
 
-    http://library.gnome.org/devel/hig-book/2.20/windows-dialog.html.en
+    http://developer.gnome.org/hig-book/stable/design-window.html.en
     paying particular attention to "initial focus", "sensible default values",
     "default buttons", ESC key termination.  Please note that the escape key
     termination only works properly if there is a dialog button defined with

TODO.txt

@@ -68,6 +68,43 @@ d) write functions to lookup a footprint from
  i) FPID
  ii) footprint alone since most old netlists don't have nicknames in them.
 
+e) Replace MODULE::m_LibRef which is a wxString with FPID.  FPID supports
+   the footprint name only which is backwards compatible with the current
+   design.
+
+f) On the first time an empty global footprint table is encountered, add
+   standard KiCad and user libraries not located in the project directory
+   or any of it's sub-directories to the global footprint library table.
+
+g) When a project is opened and the project footprint library table is
+   empty, add any user library that is located in the project path or any
+   of it's sub-directories to the project footprint library table.
+
+h) When populating the footprint library tables, use the library  file name
+   without the extension as the FPID nickname.  When duplicate names exist,
+   append an incremental integer to the nickname so that the second logic
+   libraries FPID nickname becomes logic1.  Assign FPID library nicknames
+   to each MODULE based on the legacy library search order when loading an
+   existing board that does not have fully defined MODULE FPIDs.
+
+i) Add check for KISYSMOD environment variable, on Pcbnew and CvPcb start up
+   and set it to the known directory of the default KiCad footprint libraries.
+   The code should look something like:
+
+{
+    const char* envar;
+
+    envar = getenv( "KISYSMOD" );
+
+    if( !envar )
+    {
+        envvar = knownDirOfSysMods;
+
+        setenv( "KISYSMOD", envar );
+    }
+}
+
+
 These i) and ii) merge into one if footprint alone is a valid FPID.
 Incorporate any environment variable in the the uri expansion using:
 const wxString FP_LIB_TABLE::ExpandSubtitutions( const wxString aString )

include/wxstruct.h

@@ -677,7 +677,7 @@ public:
     /**
      * Function RedrawScreen2
      * puts the crosshair back to the screen position it had before zooming
-     * @param beforePos The screen position of the crosshair before zooming
+     * @param posBefore screen position of the crosshair before zooming
      */
     void RedrawScreen2( const wxPoint& posBefore );
 

pcbnew/class_board.h

@@ -218,7 +218,7 @@ private:
     /// This is also the last used netclass after starting a track.
     wxString                m_currentNetClassName;
 
-    /// Index for #m_ViaSizeList to select the current via size.
+    /// Index for #m_ViasDimensionsList to select the current via size.
     /// 0 is the index selection of the default value Netclass
     unsigned                m_viaSizeIndex;
 

pcbnew/drag.h

@@ -27,12 +27,16 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  */
 
-#include <vector>
+#ifndef _DRAG_H_
-#include <wx/gdicmn.h>
+#define _DRAG_H_
+
+
 #include <class_track.h>
+#include <vector>
 
 
 class wxDC;
+class wxPoint;
 class EDA_DRAW_PANEL;
 class MODULE;
 class D_PAD;
@@ -84,7 +88,7 @@ public:
     ~DRAG_SEGM_PICKER() {};
 
     /**
-     * Set auxiliary parameters relative to calucaltions needed
+     * Set auxiliary parameters relative to calculations needed
      * to find track ends positions while dragging pads
      * and when modules are rotated, flipped
      */
@@ -104,6 +108,7 @@ public:
     }
 };
 
+
 class DRAG_LIST
 {
 public:
@@ -166,11 +171,13 @@ void DrawSegmentWhileMovingFootprint( EDA_DRAW_PANEL* panel, wxDC* DC );
 void EraseDragList();
 
 /**
- * function Collect_TrackSegmentsToDrag.
+ * Function Collect_TrackSegmentsToDrag.
  * used to collect track segments in drag track segment
  * Build the list of tracks connected to the ref point by calling
  * AddSegmentToDragList for each selected track
  * Net codes must be up to date, because only tracks having the right net code are tested.
+ *
+ * @param aPcb A point the the #BOARD object to collect track segment to drag.
  * @param aRefPos = reference point of connection
  * @param aLayerMask = layers mask to collect tracks
  * @param aNetCode = the net code to consider
@@ -193,3 +200,4 @@ void AddSegmentToDragList( int flag, TRACK* aTrack );
 void UndrawAndMarkSegmentsToDrag( EDA_DRAW_PANEL* aCanvas, wxDC* aDC );
 
 
+#endif    // _DRAG_H_

pcbnew/dragsegm.cpp

@@ -61,13 +61,10 @@ DRAG_SEGM_PICKER::DRAG_SEGM_PICKER( TRACK* aTrack )
 }
 
 
-/* Set auxiliary parameters relative to calucaltions needed
- * to find track ends positions while dragging pads
- * and when modules are rotated, flipped ..
- */
 void DRAG_SEGM_PICKER::SetAuxParameters()
 {
     MODULE* module = NULL;
+
     if( m_Pad_Start )
     {
         module = (MODULE *) m_Pad_Start->GetParent();
@@ -78,6 +75,7 @@ void DRAG_SEGM_PICKER::SetAuxParameters()
     {
         if( module == NULL )
             module = (MODULE *) m_Pad_End->GetParent();
+
         m_PadEndOffset = m_Track->GetEnd() - m_Pad_End->GetPosition();
     }
 
@@ -88,12 +86,7 @@ void DRAG_SEGM_PICKER::SetAuxParameters()
     }
 }
 
-/*
+
- * Calculate track ends positions while dragging pads
- * and when modules are rotated, flipped ..
- * aOffset = module or pad position offset when moving the module or pad
- * (the actual position is the module/pad position - offset)
- */
 void DRAG_SEGM_PICKER::SetTrackEndsCoordinates( wxPoint aOffset )
 {
     // the track start position is the pad position + m_PadStartOffset
@@ -119,6 +112,7 @@ void DRAG_SEGM_PICKER::SetTrackEndsCoordinates(wxPoint aOffset)
     {
         flip = m_Flipped != module->IsFlipped();
         curr_rot_offset = module->GetOrientation() - m_RotationOffset;
+
         if( flip )  // when flipping, module orientation is negated
             curr_rot_offset = - module->GetOrientation() - m_RotationOffset;
     }
@@ -154,6 +148,7 @@ void DRAG_SEGM_PICKER::SetTrackEndsCoordinates(wxPoint aOffset)
 // A sort function needed to build ordered pads lists
 extern bool sortPadsByXthenYCoord( D_PAD* const & ref, D_PAD* const & comp );
 
+
 void DRAG_LIST::BuildDragListe( MODULE* aModule )
 {
     m_Pad = NULL;
@@ -171,6 +166,7 @@ void DRAG_LIST::BuildDragListe( MODULE* aModule )
     fillList( connections );
 }
 
+
 void DRAG_LIST::BuildDragListe( D_PAD* aPad )
 {
     m_Pad = aPad;
@@ -184,14 +180,14 @@ void DRAG_LIST::BuildDragListe( D_PAD* aPad )
     fillList( connections );
 }
 
+
 // A helper function to sort track list per tracks
 bool sort_tracklist( const DRAG_SEGM_PICKER& ref, const DRAG_SEGM_PICKER& tst )
 {
     return ref.m_Track < tst.m_Track;
 }
-/** Fills m_DragList with track segments connected to pads in aConnections
+
- *  For each selected track segment the EDIT flag is set
+
- */
 void DRAG_LIST::fillList( CONNECTIONS& aConnections )
 {
     aConnections.BuildTracksCandidatesList( m_Brd->m_Track, NULL);
@@ -238,6 +234,7 @@ void DRAG_LIST::fillList(CONNECTIONS& aConnections)
                 track->end = pad;
                 track->SetState( END_ON_PAD, ON );
             }
+
             DRAG_SEGM_PICKER wrapper( track );
             m_DragList.push_back( wrapper );
         }
@@ -256,12 +253,14 @@ void DRAG_LIST::fillList(CONNECTIONS& aConnections)
     for( int ii = 0; ii < (int)m_DragList.size()-1; ii++ )
     {
         int jj = ii+1;
+
         if( m_DragList[ii].m_Track != m_DragList[jj].m_Track )
             continue;
 
         // duplicate found: merge info and remove duplicate
         if( m_DragList[ii].m_Pad_Start == NULL )
             m_DragList[ii].m_Pad_Start = m_DragList[jj].m_Pad_Start;
+
         if( m_DragList[ii].m_Pad_End == NULL )
             m_DragList[ii].m_Pad_End = m_DragList[jj].m_Pad_End;
 
@@ -277,6 +276,7 @@ void DRAG_LIST::fillList(CONNECTIONS& aConnections)
     g_DragSegmentList = m_DragList;
 }
 
+
 void DRAG_LIST::ClearList()
 {
     for( unsigned ii = 0; ii < m_DragList.size(); ii++ )
@@ -305,11 +305,6 @@ void DrawSegmentWhileMovingFootprint( EDA_DRAW_PANEL* panel, wxDC* DC )
 }
 
 
-/**
- * Function EraseDragList
- * clear the .m_Flags of all track segments found in g_DragSegmentList
- * and clear the list.
- */
 void EraseDragList()
 {
     for( unsigned ii = 0; ii < g_DragSegmentList.size(); ii++ )
@@ -319,36 +314,26 @@ void EraseDragList()
 }
 
 
-/* Add Track to the drag list, and erase it from screen
- *  flag = STARTPOINT (if the point to drag is the start point of Track) or ENDPOINT
- */
 void AddSegmentToDragList( int flag, TRACK* aTrack )
 {
     DRAG_SEGM_PICKER wrapper( aTrack );
 
-    if( (flag & STARTPOINT) )
+    if( flag & STARTPOINT )
         wrapper.m_Flag |= 1;
 
-    if( (flag & ENDPOINT) )
+    if( flag & ENDPOINT )
         wrapper.m_Flag |= 2;
 
-    if( (flag & STARTPOINT) )
+    if( flag & STARTPOINT )
         aTrack->SetFlags( STARTPOINT );
 
-    if( (flag & ENDPOINT) )
+    if( flag & ENDPOINT )
         aTrack->SetFlags( ENDPOINT );
 
     g_DragSegmentList.push_back( wrapper );
 }
 
 
-/* Build the list of tracks connected to the ref point
- * Net codes must be up to date, because only tracks having the right net code are tested.
- * aRefPos = reference point of connection
- * aLayerMask = layers mask to collect tracks
- * aNetCode = the net code to consider
- * aMaxDist = max distance from aRefPos to a track end candidate to collect the track
- */
 void Collect_TrackSegmentsToDrag( BOARD* aPcb, const wxPoint& aRefPos, int aLayerMask,
                                   int aNetCode, int aMaxDist )
 {
@@ -371,12 +356,15 @@ void Collect_TrackSegmentsToDrag( BOARD* aPcb, const wxPoint& aRefPos, int aLaye
         if( (track->GetFlags() & STARTPOINT) == 0 )
         {
             wxPoint delta = track->GetStart() - aRefPos;
+
             if( std::abs( delta.x ) <= maxdist && std::abs( delta.y ) <= maxdist )
             {
                 int dist = (int) hypot( (double) delta.x, (double) delta.y );
+
                 if( dist <= maxdist )
                 {
                     flag |= STARTPOINT;
+
                     if( track->Type() == PCB_VIA_T )
                         flag |= ENDPOINT;
                 }
@@ -386,15 +374,16 @@ void Collect_TrackSegmentsToDrag( BOARD* aPcb, const wxPoint& aRefPos, int aLaye
         if( (track->GetFlags() & ENDPOINT) == 0 )
         {
             wxPoint delta = track->GetEnd() - aRefPos;
+
             if( std::abs( delta.x ) <= maxdist && std::abs( delta.y ) <= maxdist )
             {
                 int dist = (int) hypot( (double) delta.x, (double) delta.y );
+
                 if( dist <= maxdist )
                     flag |= ENDPOINT;
             }
         }
 
-
         // Note: vias will be flagged with both STARTPOINT and ENDPOINT
         // and must not be entered twice.
         if( flag )
@@ -410,11 +399,7 @@ void Collect_TrackSegmentsToDrag( BOARD* aPcb, const wxPoint& aRefPos, int aLaye
     }
 }
 
-/*
+
- * Undraw the track segments in list, and set the IN_EDIT flag
- * Usually called after the track list is built, to prepare
- * the redraw of the list when the mouse is moved
- */
 void UndrawAndMarkSegmentsToDrag( EDA_DRAW_PANEL* aCanvas, wxDC* aDC )
 {
     for( unsigned ii = 0; ii < g_DragSegmentList.size(); ii++ )
@@ -424,13 +409,12 @@ void UndrawAndMarkSegmentsToDrag( EDA_DRAW_PANEL* aCanvas, wxDC* aDC )
         track->Draw( aCanvas, aDC, GR_XOR );
         track->SetState( IN_EDIT, ON );
 
-        if( (g_DragSegmentList[ii].m_Flag & STARTPOINT) )
+        if( g_DragSegmentList[ii].m_Flag & STARTPOINT )
             track->SetFlags( STARTPOINT );
 
-        if( (g_DragSegmentList[ii].m_Flag & ENDPOINT) )
+        if( g_DragSegmentList[ii].m_Flag & ENDPOINT )
             track->SetFlags( ENDPOINT );
 
         track->Draw( aCanvas, aDC, GR_XOR );
     }
 }
-