API Documentation improvements, especially noticable when viewing doxygen output.

pcbnew/github/github_plugin.h

@@ -32,20 +32,28 @@ struct GH_CACHE;
 
 /**
    Class GITHUB_PLUGIN
-   implements a portion of pcbnew PLUGIN to provide read only access to a github
-   repo consisting of pretty footprints.  It could have used version 3 of the
-   github.com API documented here:
+   implements a portion of pcbnew's PLUGIN interface to provide read only access
+   to a github repo consisting of pretty footprints, and optionally provides "Copy On Write"
+   support of edited footprints.
+
+   <p>It could have used version 3 of the github.com API documented here:
 
    <pre>
        http://developer.github.com
        https://help.github.com/articles/creating-an-access-token-for-command-line-use
    </pre>
 
-   but it does not. Rather it simply reads in a zip file of the repo and unzips
-   it from RAM as needed. <b>Therefore this "Github" plugin type is read only
-   for accessing remote pretty libraries at https://github.com.</b> The "Library
-   Path" in the fp-lib-table row for a Github library should be set to the full
-   https:// URL. For example:
+   but it does not, since a better technique was discovered. Cleverly this
+   plugin simply reads in a zip file of the repo and unzips it from RAM as
+   needed. Therefore this "Github" plugin is <b>read only for accessing remote
+   pretty libraries at https://github.com.</b>
+
+   <p>The fp-lib-table dialog is entered via menu choice "Preferences | Library
+   Tables". For easy options editing in the current row, click on the "Edit
+   Options" button. The "Library Path" in the fp-lib-table row for a Github
+   library should be set to the full https:// URL.
+
+   <p>For example:
 
    <pre>
         https://github.com/liftoff-sr/pretty_footprints
@@ -58,52 +66,79 @@ struct GH_CACHE;
    </pre>
    <p>
 
-   This PLUGIN also supports "Copy On Write", a.k.a. "COW". Thus a Github
-   library defined in either fp-lib-table (project or global) will take an
-   optional option called <b>allow_pretty_writing_to_this_dir</b>. This option
-   is essentially the "Library Path" for a local "KiCad" (pretty) type library
-   which is combined to make up the Github library found in the same
-   fp-lib-table row. If the option is missing, then the Github library is read
-   only as always. If the option is present for a Github library, then any
-   writes to this hybrid library will go to the local *.pretty directory. Note
-   that the github.com resident portion of this hybrid COW library is always
-   read only, meaning you cannot delete anything or modify any footprint at
-   github directly. The aggregate library "Type" remains "Github", but it
-   consists of a local R/W portion and a remote R/O portion.
-
-   <p>
-
-   Any footprint loads will always give precedence to the local footprints found
-   in the pretty dir given by option <b>allow_pretty_writing_to_this_dir</b>. So
-   once you have written to the COW library's local directory by doing a
-   footprint save, no github updates will be seen when loading a footprint by
-   the same name as one for which you've written locally.
-
-   <p>
-
-   Always keep a separate local *.pretty directory for each Github library,
+   The "Plugin Type" should be set to "Github".
+
+   <p>This plugin also supports "Copy On Write", a.k.a. "COW". Thus a Github
+   library may take an optional option called
+   <b>allow_pretty_writing_to_this_dir</b>. This option is essentially the
+   "Library Path" for a local "KiCad" (pretty) type library which is combined to
+   make up the Github library found in the same fp-lib-table row. If the option
+   is missing, then the Github library is read only as always. If the option is
+   present for a Github library, then any writes to this hybrid library will go
+   to the local *.pretty directory. Note that the github.com resident portion of
+   this hybrid COW library is always read only, meaning you cannot delete
+   anything or modify any footprint at github directly. The aggregate library
+   type remains "Github" in your discussions, but it consists of a local R/W
+   portion and a remote R/O portion.
+
+   <p>Below is an fp-lib-table entry for the case without option
+   <b>allow_pretty_writing_to_this_dir</b>:
+
+    <table>
+        <tr>
+        <th>Nickname</th><th>Library Path</th><th>Plugin Type</th><th>Options</th><th>Description</th>
+        </tr>
+
+        <tr>
+        <td>github</td><td>https://github.com/liftoff-sr/pretty_footprints</td><td>Github</td>
+            <td></td><td>Liftoff's GH footprints</td>
+        </tr>
+   </table>
+
+   Below is an fp-lib-table entry with the COW option given. Note the use of the environment variable
+   ${HOME}, as an example only.  The github.pretty directory is based in ${HOME}/pretty/.  Anytime you
+   use option allow_pretty_writing_to_this_dir, you will create that directory manually and it must
+   end in extension <b>.pretty</b>.
+
+    <table>
+        <tr>
+        <th>Nickname</th><th>Library Path</th><th>Plugin Type</th><th>Options</th><th>Description</th>
+        </tr>
+
+        <tr>
+
+        <td>github</td><td>https://github.com/liftoff-sr/pretty_footprints</td><td>Github</td>
+            <td>allow_pretty_writing_to_this_dir=${HOME}/pretty/github.pretty</td>
+            <td>Liftoff's GH footprints</td>
+        </tr>
+   </table>
+
+   <p>Any footprint loads will always give precedence to the local footprints
+   found in the pretty dir given by option
+   <b>allow_pretty_writing_to_this_dir</b>. So once you have written to the COW
+   library's local directory by doing a footprint save, no github updates will
+   be seen when loading a footprint by the same name as one for which you've
+   written locally.
+
+   <p>Always keep a separate local *.pretty directory for each Github library,
    never combine them by referring to the same directory more than once. Also,
-   do not also use the same COW (*.pretty) directory in a "Kicad" fp-lib-table
+   do not also use the same COW (*.pretty) directory in a "KiCad" fp-lib-table
    entry. This would likely create a mess. The COW directory should be manually
    created in advance, and the directory name must end with ".pretty". The value
    of the option <b>allow_pretty_writing_to_this_dir</b> will be path
    substituted with any environment variable strings embedded, just like the
    "Library Path" is.
 
-   <p>
-
-   What's the point of COW? It is to turbo-charge the sharing of footprints. If
-   you periodically email your COW pretty footprint modifications to the Github
-   repo maintainer, you can help update the Github copy. Simply email the
-   individual *.kicad_mod file you find in your COW directories. After you've
+   <p>What's the point of COW? It is to turbo-charge the sharing of footprints.
+   If you periodically email your COW pretty footprint modifications to the
+   Github repo maintainer, you can help update the Github copy. Simply email the
+   individual *.kicad_mod files you find in your COW directories. After you've
    received confirmation that your changes have been committed up at github.com,
    you can safely delete your COW file(s) and those from github.com will flow
    down. Your goal should be to keep the COW file set as small as possible by
    contributing frequently to the shared master copies at https://github.com.
 
-   <p>
-
-   Note that if you use the module editor to delete a footprint and it is
+   <p>Note that if you use the module editor to delete a footprint and it is
    present in the COW local dir, it will get deleted from there. However, it may
    not be deleted from the library as a whole if the footprint of the same name
    also exists in the github repo. In this case deleting the local copy will
@@ -112,6 +147,14 @@ struct GH_CACHE;
    remember you cannot modify the github copy except by emailing a COW
    modification to the repo maintainer.
 
+   <p>If you happen to be the repo maintainer, then the obvious solution for you
+   is to make your COW directory <b>be</b> your working copy directory. From
+   there you can push to github. And you can receive *.kicad_mod files by email
+   and put them into your local working copy directory also and do diffs,
+   reverting or denying when appropriate, editing when appropriate before
+   pushing or denying the change. Ultimately you would owe the sender either a
+   note of acceptance or denial by email.
+
    @author Dick Hollenbeck
    @date Original date: 10-Sep-2013
 

pcbnew/io_mgr.h

@@ -286,11 +286,11 @@ public:
      * Function FootprintEnumerate
      * returns a list of footprint names contained within the library at @a aLibraryPath.
      *
-     * @param aLibraryPath is a locator for the "library", usually a directory
-     *   or file containing several footprints.
+     * @param aLibraryPath is a locator for the "library", usually a directory, file,
+     *   or URL containing several footprints.
      *
      * @param aProperties is an associative array that can be used to tell the
-     *  plugin how to access the library.
+     *  plugin anything needed about how to perform with respect to @a aLibraryPath.
      *  The caller continues to own this object (plugin may not delete it), and
      *  plugins should expect it to be optionally NULL.
      *
@@ -307,8 +307,8 @@ public:
      * loads a footprint having @a aFootprintName from the @a aLibraryPath containing
      * a library format that this PLUGIN knows about.
      *
-     * @param aLibraryPath is a locator for the "library", usually a directory
-     *   or file containing several footprints.
+     * @param aLibraryPath is a locator for the "library", usually a directory, file,
+     *   or URL containing several footprints.
      *
      * @param aFootprintName is the name of the footprint to load.
      *
@@ -331,9 +331,8 @@ public:
      * will write @a aModule to an existing library located at @a aLibraryPath.
      * If a footprint by the same name already exists, it is replaced.
      *
-     * @param aLibraryPath is a locator for the "library", usually a directory
-     *      or file containing several footprints. This is where the footprint is
-     *      to be stored.
+     * @param aLibraryPath is a locator for the "library", usually a directory, file,
+     *   or URL containing several footprints.
      *
      * @param aFootprint is what to store in the library. The caller continues
      *    to own the footprint after this call.
@@ -351,15 +350,15 @@ public:
 
     /**
      * Function FootprintDelete
-     * deletes the @a aFootprintName from the library at @a aLibraryPath.
+     * deletes @a aFootprintName from the library at @a aLibraryPath.
      *
-     * @param aLibraryPath is a locator for the "library", usually a directory
-     *   or file containing several footprints.
+     * @param aLibraryPath is a locator for the "library", usually a directory, file,
+     *   or URL containing several footprints.
      *
      * @param aFootprintName is the name of a footprint to delete from the specified library.
      *
      * @param aProperties is an associative array that can be used to tell the
-     *  library create function anything special, because it can take any number of
+     *  library delete function anything special, because it can take any number of
      *  additional named tuning arguments that the plugin is known to support.
      *  The caller continues to own this object (plugin may not delete it), and
      *  plugins should expect it to be optionally NULL.
@@ -375,8 +374,8 @@ public:
      * error to attempt to create an existing library or to attempt to create
      * on a "read only" location.
      *
-     * @param aLibraryPath is a locator for the "library", usually a directory
-     *   or file which will contain footprints.
+     * @param aLibraryPath is a locator for the "library", usually a directory, file,
+     *   or URL containing several footprints.
      *
      * @param aProperties is an associative array that can be used to tell the
      *  library create function anything special, because it can take any number of
@@ -414,6 +413,9 @@ public:
      * returns true iff the library at @a aLibraryPath is writable.  (Often
      * system libraries are read only because of where they are installed.)
      *
+     * @param aLibraryPath is a locator for the "library", usually a directory, file,
+     *   or URL containing several footprints.
+     *
      * @throw IO_ERROR if no library at aLibraryPath exists.
      */
     virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );