Improved PLUGIN documentation in io_mgr.h

    enum PCB_FILE_T

    {

        KICAD,

        // add your type here.

        // EAGLE,

        // ALTIUM,

        // etc.

     * Function PluginRelease

     * releases a PLUGIN back to the system, and may cause it to be unloaded from memory.

     *

     * @param aPlugin is the one to be released, and which is no longer usable.

     * @param aPlugin is the one to be released, and which is no longer usable

     *  after calling this.

     */

    static void PluginRelease( PLUGIN* aPlugin );

    /**

     * Function Load

     * finds the requested PLUGIN and loads a BOARD, or throws an exception trying.

     * finds the requested PLUGIN and if found, calls the PLUGIN->Load(..) funtion

     * on it using the arguments passed to this function.  After the PLUGIN->Load()

     * function returns, the PLUGIN is Released() as part of this call.

     *

     * @param aFileType is the PCB_FILE_T of file to load.

     *

    static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,

            BOARD* aAppendToMe = NULL, PROPERTIES* aProperties = NULL );

    // etc.

    /**

     * Function Save

     * will write a full aBoard to a storage file in a format that this

     * implementation knows about, or it can be used to write a portion of

     * aBoard to a special kind of export file.

     *

     * @param aFileName is the name of a file to save to on disk.

     * @param aBoard is the BOARD document (data tree) to save or export to disk.

     *

     * @param aProperties is an associative array that can be used to tell the

     *  saver how to save the file, because it can take any number of

     *  additional named tuning arguments that the plugin is known to support.

     *

     * @throw IO_ERROR if there is a problem saving or exporting.

     */

    static void Save( PCB_FILE_T aFileType, const wxString& aFileName,

            PROPERTIES* aProperties = NULL );

};

 * <pre>

 *   try

 *   {

 *        pi->Load(...);

 *        IO_MGR::Load(...);

 *   or

 *        IO_MGR::Save(...);

 *   }

 *   catch( IO_ERROR ioe )

 *   {

    };

    //-----<PUBLIC PLUGIN API>-------------------------------------------------

    /**

     * Function PluginName

     * returns a brief hard coded name for this PLUGIN.

     */

    virtual const wxString& PluginName() = 0;

    //-----<BOARD STUFF>----------------------------------------------------

    /**

     * Function Load

     * loads a board file from some input file format that this implementation

     * knows about.

     * loads a board file, or a portion of one, from some input file format

     * that this PLUGIN implementation knows about. This may be used to load an

     * entire new BOARD, or to augment an existing one if \a aAppendToMe is not NULL.

     *

     * @param aFileName is the name of the file to load and may be foreign in

     * @param aFileName is the name of the file to use as input and may be foreign in

     *  nature or native in nature.

     *

     * @param aAppendToMe is an existing BOARD to append to but is often NULL

     *  meaning do not append.

     * @param aAppendToMe is an existing BOARD to append to, but if NULL then

     *   this means "do not append, rather load anew".

     *

     * @param aProperties is an associative array that can be used to tell the

     *  loader how to load the file, because it can take any number of

     *  additional named arguments that the plugin is known to support.

     *  additional named arguments that the plugin is known to support. These are

     *  tuning parameters for the import or load.  The caller continues to own

     *  this object (plugin may not delete it), and plugins should expect it to

     *  be optionally NULL.

     *

     * @return BOARD* - the successfully loaded board, and caller owns it.

     * @return BOARD* - the successfully loaded board, or the same one as aAppendToMe

     *  if aAppendToMe was not NULL, and caller owns it.

     *

     * @throw IO_ERROR if there is a problem loading, and its contents should

     *  say what went wrong.

     *  say what went wrong, using line number and character offsets of the

     *  input file if possible.

     */

    virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,

                        PROPERTIES* aProperties = NULL );

    /**

     * Function Save

     * will write a full aBoard to a storage file in a format that only this

     * implementation knows about.  Or it can be used to write a portion of

     * will write a full aBoard to a storage file in a format that this

     * PLUGIN implementation knows about, or it can be used to write a portion of

     * aBoard to a special kind of export file.

     *

     * @param aFileName is the name of a file to save to on disk.

     *

     * @param aProperties is an associative array that can be used to tell the

     *  saver how to save the file, because it can take any number of

     *  additional named arguments that the plugin is known to support.

     *  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.

     *

     * @throw IO_ERROR if there is a problem loading.

     * @throw IO_ERROR if there is a problem saving or exporting.

     */

    virtual void Save( const wxString* aFileName, BOARD* aBoard,

                    PROPERTIES* aProperties = NULL );

    //-----</BOARD STUFF>---------------------------------------------------

    //-----</PUBLIC PLUGIN API>------------------------------------------------

};

#if 0

    ///--------- Should split into two PLUGIN base types here, rather than being combined like this

#if 0

    //-----<SCHEMATIC STUFF>------------------------------------------------

    // Should split into schematic specific PLUGIN base type

    /**

     * Function Load

    /**

     * Function Save

     * will write aBoard to a storage file in a format that only this

     * will write aSchematic to a storage file in a format that only this

     * implementation knows about.

     *

     * @param aFileName is the name of a file to save to on disk.

    //-----</SCHEMATIC STUFF>----------------------------------------------

#endif

};

#endif // IO_MGR_H_