haskal
/
kicad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doxygen warning fixes and coding policy comment changes.

This commit is contained in:
Wayne Stambaugh 2017-06-15 20:31:42 -04:00
parent 996bcdf458
commit dab73e172b
5 changed files with 183 additions and 212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
Documentation/development/coding-style-policy.md
View File

@ -1,12 +1,12 @@
# KiCad C++ Source Code Style Guide # # KiCad C++ Source Code Style Guide #
Latest Publishing: February 2013 Latest Publishing: February 2017
First Published: September 2010 First Published: September 2010
written by written by
Wayne Stambaugh \<<stambaughw@verizon.net>\> Wayne Stambaugh \<<stambaughw@gmail.com>\>
and and
Dick Hollenbeck \<<dick@softplc.com>\> Dick Hollenbeck \<<dick@softplc.com>\>
@ -129,8 +129,7 @@ enables clever and concise Doxygen comments.
**Example** **Example**
~~~~~~~~~~~~~{.cpp} ~~~~~~~~~~~~~{.cpp}
/*/** */* /*/** */*
* Function SetFoo * Copy aFoo into this instance.
* takes aFoo and copies it into this instance.
*/ */
void SetFoo( int aFoo ); void SetFoo( int aFoo );
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -174,18 +173,21 @@ one or more blank lines above them. One blank line is preferred.
## 3.2 Doxygen ## {#doxygen} ## 3.2 Doxygen ## {#doxygen}
Doxygen is a C++ source code documenting tool used by the project. Descriptive Doxygen is a C++ source code documenting tool used by the project. Descriptive
*.html files can be generated from the source code by installing Doxygen and *.html files can be generated from the source code by installing Doxygen and
building the target named **doxygen-docs**. building the target named **doxygen-docs** and **dev-docs** that include this
document.
$ cd <kicad_build_base> $ cd <kicad_build_base>
$ make doxygen-docs $ make doxygen-docs
The \*.html files will be placed into The generated source \*.html files will be placed into
\<kicad\_project\_base\>/Documentation/doxygen/html/ \<kicad\_project\_base\>/Documentation/doxygen/html/ and the developer's
\*.html files will be placed into
\<kicad\_project\_base\>/Documentation/development/doxygen/html/
Doxygen comments are used to build developer documentation from the Doxygen comments are used to build developer documentation from the
source code. They should normally be only placed in header files and not source code. They should normally be only placed in header files and not
in \*.cpp files. This eliminates the obligation to keep two comments in in \*.cpp files. This eliminates the obligation to keep two comments in
agreement with each other. is if the class, function, or enum, etc. is agreement with each other. If the class, function, or enum, etc. is
only defined in a \*.cpp source file and not present in any header file, only defined in a \*.cpp source file and not present in any header file,
in which case the Doxygen comments should go into the \*.cpp source file. in which case the Doxygen comments should go into the \*.cpp source file.
Again, avoid duplicating the Doxygen comments in both the header and Again, avoid duplicating the Doxygen comments in both the header and
@ -208,28 +210,31 @@ static) function known only to a \*.cpp file. The format of a function
comment is chosen to serve a dual purpose role: delineation of the comment is chosen to serve a dual purpose role: delineation of the
function declaration within the source code and to create a consistent function declaration within the source code and to create a consistent
leading sentence in the doxygen html output. The chosen format is leading sentence in the doxygen html output. The chosen format is
“Function \<name\>” as shown in the example below. to use a descriptive single line sentence, followed by a blank line,
followed by an optional detailed description as the shown in the example
below.
**Example** **Example**
~~~~~~~~~~~~~{.cpp} ~~~~~~~~~~~~~{.cpp}
/*/** */* /*/** */*
* Function Print * Format and write text to an output stream.
* formats and writes text to the output stream. *
* @param nestLevel is the multiple of spaces to precede the output with. * A really detailed description goes here if it's needed.
* @param fmt is a printf() style format string. *
* @param aMestLevel is the multiple of spaces to precede the output with.
* @param aFmt is a printf() style format string.
* @param ... is a variable list of parameters that will get blended into * @param ... is a variable list of parameters that will get blended into
* the output under control of the format string. * the output under control of the format string.
* @return int - the number of characters output. * @return the number of characters output.
* @throw IO_ERROR, if there is a problem outputting, such asisk. * @throw IO_ERROR, if there is a problem outputting.
*/ */
int PRINTF_FUNC Print( int nestLevel, int PRINTF_FUNC Print( int aNestLevel, const char* aFmt, ... );
const char* fmt, ... );
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The “Function \<name\>” text goes on the 2nd line of the comment. The The single line description goes on the 2nd line of the comment. The
\@return keyword if present, should show the type of the return value \@return keyword if present, should describe the return value followed
followed by a hiphen. The \@param keyword names a function parameter by a hyphen. The \@param keyword names a function parameter and the text
and the text following should flow like a normal English sentence. following should flow like a normal English sentence.
### 3.2.2 Class Comments ### {#class_comments} ### 3.2.2 Class Comments ### {#class_comments}
A class comment describes a class declaration by giving the purpose and A class comment describes a class declaration by giving the purpose and
@ -241,14 +246,15 @@ multiple paragraphs.
**Example** **Example**
~~~~~~~~~~~~~{.cpp} ~~~~~~~~~~~~~{.cpp}
/*/** */* /*/** */*
* Class OUTPUTFORMATTER * An interface (abstract) class used to output UTF8 text in a
* is an important interface (abstract) class used to output UTF8 text in * convenient way.
* a convenient way. The primary interface is "printf() - like" but *
* with support for indentation control. The destination of the 8 bit * The primary interface is "printf() like" but with support for
* wide text is up to the implementer. * indentation control. The destination of the 8 bit wide text is
* up to the implementer.
* <p> * <p>
* The implementer only has to implement the write() function, but can * The implementer only has to implement the write() function, but
* also optionally re-implement GetQuoteChar(). * can also optionally re-implement GetQuoteChar().
* <p> * <p>
* If you want to output a wxString, then use CONV_TO_UTF8() on it * If you want to output a wxString, then use CONV_TO_UTF8() on it
* before passing it as an argument to Print(). * before passing it as an argument to Print().
@ -440,7 +446,7 @@ Each header file should include an \#ifndef which is commonly used to
prevent compiler errors in the case where the header file is seen prevent compiler errors in the case where the header file is seen
multiple times in the code stream presented to the compiler. Just multiple times in the code stream presented to the compiler. Just
after the license statement, at the top of the file there should be after the license statement, at the top of the file there should be
lines similar to these (but with a filename specific token other than lines similar to these (but with a file name specific token other than
`RICHIO_H_`): `RICHIO_H_`):
~~~~~~~~~~~~~{.cpp} ~~~~~~~~~~~~~{.cpp}
@ -558,8 +564,7 @@ below was taken directly from the KiCad source.
/*/** */* /*/** */*
* Struct IOError * A class used to hold an error message and may be used to throw exceptions
* is a class used to hold an error message and may be used to throw exceptions
* containing meaningful error messages. * containing meaningful error messages.
*/ */
struct IOError struct IOError
@ -579,9 +584,7 @@ below was taken directly from the KiCad source.
/*/** */* /*/** */*
* Class LINE_READER * Read single lines of text into a buffer and increments a line number counter.
* reads single lines of text into its buffer and increments a line number counter.
* It throws an exception if a line is too long.
*/ */
class LINE_READER class LINE_READER
{ {
@ -597,12 +600,10 @@ below was taken directly from the KiCad source.
public: public:
/*/** */* /*/** */*
* Constructor LINE_READER * @param aFile is an open file in "ascii" mode, not binary mode.
* takes an open FILE and the size of the desired line buffer. * @param aMaxLineLength is the number of bytes to use in the line buffer.
* @param aFile An open file in "ascii" mode, not binary mode.
* @param aMaxLineLength The number of bytes to use in the line buffer.
*/ */
LINE_READER( FILE* aFile, unsigned aMaxLineLength ); LINE_READER( FILE* aFile, unsigned aMaxLineLength );
~LINE_READER() ~LINE_READER()
{ {
@ -619,12 +620,11 @@ below was taken directly from the KiCad source.
*/ */
/*/** */* /*/** */*
* Function ReadLine * Read a line of text into the buffer and increments the line number
* reads a line of text into the buffer and increments the line number * counter.
* counter. If the line is larger than the buffer size, then an exception *
* is thrown. * @return is the number of bytes read, 0 at end of file.
* @return int - The number of bytes read, 0 at end of file. * @throw IO_ERROR when a line is too long.
* @throw IOError only when a line is too long.
*/ */
int ReadLine(); int ReadLine();
@ -647,15 +647,16 @@ below was taken directly from the KiCad source.
/*/** */* /*/** */*
* Class OUTPUTFORMATTER * An interface (abstract class) used to output ASCII text in a convenient way.
* is an interface (abstract class) used to output ASCII text in a convenient *
* way. The primary interface is printf() like but with support for indentation * The primary interface is printf() like with support for indentation control.
* control. The destination of the 8 bit wide text is up to the implementer. * The destination of the 8 bit wide text is up to the implementer. If you want
* If you want to output a wxString, then use CONV_TO_UTF8() on it before passing * to output a wxString, then use CONV_TO_UTF8() on it before passing it as an
* it as an argument to Print(). * argument to Print().
* <p> * <p>
* Since this is an abstract interface, only classes derived from this one * Since this is an abstract interface, only classes derived from this one
* will be the implementations. * will be the implementations.
* </p>
*/ */
class OUTPUTFORMATTER class OUTPUTFORMATTER
{ {
@ -675,58 +676,54 @@ below was taken directly from the KiCad source.
public: public:
/*/** */* /*/** */*
* Function Print * Format and write text to the output stream.
* formats and writes text to the output stream.
* *
* @param nestLevel The multiple of spaces to preceed the output with. * @param nestLevel is the multiple of spaces to preceed the output with.
* @param fmt A printf() style format string. * @param fmt is a printf() style format string.
* @param ... a variable list of parameters that will get blended into * @param ... is a variable list of parameters that will get blended into
* the output under control of the format string. * the output under control of the format string.
* @return int - the number of characters output. * @return the number of characters output.
* @throw IOError, if there is a problem outputting, such as a full disk. * @throw IO_ERROR if there is a problem outputting, such as a full disk.
*/ */
virtual int PRINTF_FUNC Print( int nestLevel, const char* fmt, ... ) = 0; virtual int PRINTF_FUNC Print( int nestLevel, const char* fmt, ... ) = 0;
/*/** */* /*/** */*
* Function GetQuoteChar * Return the quoting character required for aWrapee.
* performs quote character need determination. *
* It returns the quote character as a single character string for a given * Return the quote character as a single character string for a given
* input wrapee string. If the wrappee does not need to be quoted, * input wrapee string. If the wrappee does not need to be quoted,
* the return value is "" (the null string), such as when there are no * the return value is "" (the null string), such as when there are no
* delimiters in the input wrapee string. If you want the quote_char * delimiters in the input wrapee string. If you want the quote character
* to be assuredly not "", then pass in "(" as the wrappee. * to be assuredly not "", then pass in "(" as the wrappee.
* <p> * <p>
* Implementations are free to override the default behavior, which is to * Implementations are free to override the default behavior, which is to
* call the static function of the same name. * call the static function of the same name.
* </p>
* @param wrapee A string that might need wrapping on each end. *
* @return const char* - the quote_char as a single character string, or "" * @param aWrapee is a string that might need wrapping on each end.
* @return the quote character as a single character string, or ""
* if the wrapee does not need to be wrapped. * if the wrapee does not need to be wrapped.
*/ */
virtual const char* GetQuoteChar( const char* wrapee ) = 0; virtual const char* GetQuoteChar( const char* aWrapee ) = 0;
virtual ~OUTPUTFORMATTER() {} virtual ~OUTPUTFORMATTER() {}
/*/** */* /*/** */*
* Function GetQuoteChar * Get the quote character according to the Specctra DSN specification.
* performs quote character need determination according to the Specctra DSN *
* specification. * @param aWrapee is a string that might need wrapping on each end.
* @param aQuoteChar is a single character C string which provides the current
* @param wrapee A string that might need wrapping on each end.
* @param quote_char A single character C string which provides the current
* quote character, should it be needed by the wrapee. * quote character, should it be needed by the wrapee.
* *
* @return const char* - the quote_char as a single character string, or "" * @return the quote_character as a single character string, or ""
* if the wrapee does not need to be wrapped. * if the wrapee does not need to be wrapped.
*/ */
static const char* GetQuoteChar( const char* wrapee, const char* quote_char ); static const char* GetQuoteChar( const char* aWrapee, const char* aQuoteChar );
}; };
/*/** */* /*/** */*
* Class STRINGFORMATTER * Implement an OUTPUTFORMATTER to a memory buffer.
* implements OUTPUTFORMATTER to a memory buffer. After Print()ing the
* string is available through GetString()
*/ */
class STRINGFORMATTER : public OUTPUTFORMATTER class STRINGFORMATTER : public OUTPUTFORMATTER
{ {
@ -739,8 +736,7 @@ below was taken directly from the KiCad source.
public: public:
/*/** */* /*/** */*
* Constructor STRINGFORMATTER * Reserve space in the buffer
* reserves space in the buffer
*/ */
STRINGFORMATTER( int aReserve = 300 ) : STRINGFORMATTER( int aReserve = 300 ) :
buffer( aReserve, '\0' ) buffer( aReserve, '\0' )
@ -749,8 +745,7 @@ below was taken directly from the KiCad source.
/*/** */* /*/** */*
* Function Clear * Clears the buffer and empties the internal string.
* clears the buffer and empties the internal string.
*/ */
void Clear() void Clear()
{ {
@ -758,8 +753,7 @@ below was taken directly from the KiCad source.
} }
/*/** */* /*/** */*
* Function StripUseless * Remove whitespace, '(', and ')' from the internal string.
* removes whitespace, '(', and ')' from the mystring.
*/ */
void StripUseless(); void StripUseless();

197
eeschema/sch_io_mgr.h
View File

@ -46,8 +46,7 @@ class SCH_IO_MGR
public: public:
/** /**
* Enum SCH_FILE_T * A set of file types that the #SCH_IO_MGR knows about, and for which there
* is a set of file types that the SCH_IO_MGR knows about, and for which there
* has been a plugin written. * has been a plugin written.
*/ */
enum SCH_FILE_T enum SCH_FILE_T
@ -61,22 +60,22 @@ public:
}; };
/** /**
* Function FindPlugin * Return a #SCH_PLUGIN which the caller can use to import, export, save, or load
* returns a SCH_PLUGIN which the caller can use to import, export, save, or load * design documents.
* design documents. The returned SCH_PLUGIN, may be reference counted, so please
* call PluginRelease() when you are done using the returned SCH_PLUGIN. It may or
* may not be code running from a DLL/DSO.
* *
* @param aFileType is from SCH_FILE_T and tells which plugin to find. * The returned #SCH_PLUGIN, may be reference counted, so please call PluginRelease()
* when you are done using the returned #SCH_PLUGIN. It may or may not be code running
* from a DLL/DSO.
* *
* @return SCH_PLUGIN* - the plugin corresponding to aFileType or NULL if not found. * @param aFileType is from #SCH_FILE_T and tells which plugin to find.
*
* @return the plugin corresponding to aFileType or NULL if not found.
* Caller owns the returned object, and must call PluginRelease when done using it. * Caller owns the returned object, and must call PluginRelease when done using it.
*/ */
static SCH_PLUGIN* FindPlugin( SCH_FILE_T aFileType ); static SCH_PLUGIN* FindPlugin( SCH_FILE_T aFileType );
/** /**
* Function PluginRelease * Release a #SCH_PLUGIN back to the system, and may cause it to be unloaded from memory.
* releases a SCH_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. * after calling this.
@ -84,76 +83,75 @@ public:
static void ReleasePlugin( SCH_PLUGIN* aPlugin ); static void ReleasePlugin( SCH_PLUGIN* aPlugin );
/** /**
* Function ShowType * Return a brief name for a plugin, given aFileType enum.
* returns a brief name for a plugin, given aFileType enum.
*/ */
static const wxString ShowType( SCH_FILE_T aFileType ); static const wxString ShowType( SCH_FILE_T aFileType );
/** /**
* Function EnumFromStr * Return the #SCH_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc.
* returns the SCH_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc.
*/ */
static SCH_FILE_T EnumFromStr( const wxString& aFileType ); static SCH_FILE_T EnumFromStr( const wxString& aFileType );
/** /**
* Function GetFileExtension * Return the file extension for \a aFileType.
* returns the file extension for \a aFileType.
* *
* @param aFileType The #SCH_FILE_T type. * @param aFileType is the #SCH_FILE_T type.
* @return A wxString object containing the file extension for \a aFileType or an empty *
* string if \a aFileType is invalid. * @return the file extension for \a aFileType or an empty string if \a aFileType is invalid.
*/ */
static const wxString GetFileExtension( SCH_FILE_T aFileType ); static const wxString GetFileExtension( SCH_FILE_T aFileType );
/** /**
* Function GuessPluginTypeFromLibPath * Return a plugin type given a footprint library's libPath.
* returns a plugin type given a footprint library's libPath.
*/ */
static SCH_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath ); static SCH_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
/** /**
* Function Load * Load the requested #SCH_PLUGIN and if found, calls the SCH_PLUGIN->Load(..) function
* finds the requested SCH_PLUGIN and if found, calls the SCH_PLUGIN->Load(..) function
* on it using the arguments passed to this function. After the SCH_PLUGIN->Load() * on it using the arguments passed to this function. After the SCH_PLUGIN->Load()
* function returns, the SCH_PLUGIN is Released() as part of this call. * function returns, the #SCH_PLUGIN is Released() as part of this call.
*
* @param aFileType is the #SCH_FILE_T of file to load.
* *
* @param aFileType is the SCH_FILE_T of file to load.
* @param aFileName is the name of the file to load. * @param aFileName is the name of the file to load.
*
* @param aKiway is the #KIWAY object used to access the component libraries loaded * @param aKiway is the #KIWAY object used to access the component libraries loaded
* by the project. * by the project.
* @param aAppendToMe is an existing #SCHEMATIC to append to, use NULL if a new *
* #SCHEMATIC load is wanted. * @param aAppendToMe is an existing #SCH_SHEET to append to, use NULL if a new
* #SCH_SHEET load is wanted.
*
* @param aProperties is an associative array that allows the caller to pass additional * @param aProperties is an associative array that allows the caller to pass additional
* tuning parameters to the SCH_PLUGIN. * tuning parameters to the #SCH_PLUGIN.
* *
* @return SCHEMATIC* - caller owns it, never NULL because exception thrown if error. * @return the loaded schematic which the caller owns. This is never NULL because
* exception thrown if an error occurs.
* *
* @throw IO_ERROR if the SCH_PLUGIN cannot be found, file cannot be found, * @throw IO_ERROR if the #SCH_PLUGIN cannot be found, file cannot be found
* or file cannot be loaded. * or file cannot be loaded.
*/ */
static SCH_SHEET* Load( SCH_FILE_T aFileType, const wxString& aFileName, KIWAY* aKiway, static SCH_SHEET* Load( SCH_FILE_T aFileType, const wxString& aFileName, KIWAY* aKiway,
SCH_SHEET* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL ); SCH_SHEET* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL );
/** /**
* Function Save * Write either a full aSchematic to a storage file in a format that this
* will write either a full aSchematic to a storage file in a format that this
* implementation knows about, or it can be used to write a portion of * implementation knows about, or it can be used to write a portion of
* aSchematic to a special kind of export file. * aSchematic to a special kind of export file.
* *
* @param aFileType is the SCH_FILE_T of file to save. * @param aFileType is the #SCH_FILE_T of file to save.
* *
* @param aFileName is the name of a file to save to on disk. * @param aFileName is the name of a file to save to on disk.
* @param aSchematic is the SCHEMATIC document (data tree) to save or export to disk.
* *
* @param aSchematic is the in memory document tree from which to extract information * @param aSchematic is the #SCH_SCREN document (data tree) to save or export to disk.
* when writing to \a aFileName. The caller continues to own the SCHEMATIC, and *
* the plugin should refrain from modifying the SCHEMATIC if possible. * @param aKiway is the #KIWAY object used to access the component libraries loaded
* by the project.
* *
* @param aProperties is an associative array that can be used to tell the * @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 * saver how to save the file, because it can take any number of
* additional named tuning 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 * The caller continues to own this object (plugin may not delete it), and
* plugins should expect it to be optionally NULL. * plugins should expect it to be optionally NULL.
* *
* @throw IO_ERROR if there is a problem saving or exporting. * @throw IO_ERROR if there is a problem saving or exporting.
*/ */
@ -163,8 +161,7 @@ public:
/** /**
* Class SCH_PLUGIN * Base class that schematic file and library loading and saving plugins should derive from.
* is a base class that SCHEMATIC loading and saving plugins should derive from.
* Implementations can provide either Load() or Save() functions, or both. * Implementations can provide either Load() or Save() functions, or both.
* SCH_PLUGINs throw exceptions, so it is best that you wrap your calls to these * SCH_PLUGINs throw exceptions, so it is best that you wrap your calls to these
* functions in a try catch block. Plugins throw exceptions because it is illegal * functions in a try catch block. Plugins throw exceptions because it is illegal
@ -191,22 +188,17 @@ public:
//-----<PUBLIC SCH_PLUGIN API>------------------------------------------------- //-----<PUBLIC SCH_PLUGIN API>-------------------------------------------------
/** /**
* * Returns a brief hard coded name for this SCH_PLUGIN.
* Function GetName
* returns a brief hard coded name for this SCH_PLUGIN.
*/ */
virtual const wxString GetName() const = 0; virtual const wxString GetName() const = 0;
/** /**
* Function GetFileExtension * Returns the file extension for the #SCH_PLUGIN.
* returns the file extension for the SCH_PLUGIN.
*/ */
virtual const wxString GetFileExtension() const = 0; virtual const wxString GetFileExtension() const = 0;
/** /**
* Function GetModifyHash * Return the modification hash from the library cache.
*
* returns the modification hash from the library cache.
* *
* @note This is temporary until the new s-expr file format is implement. The new file * @note This is temporary until the new s-expr file format is implement. The new file
* format will embed symbols instead of referencing them from the library. This * format will embed symbols instead of referencing them from the library. This
@ -219,16 +211,17 @@ public:
virtual void SaveLibrary( const wxString& aFileName, const PROPERTIES* aProperties = NULL ); virtual void SaveLibrary( const wxString& aFileName, const PROPERTIES* aProperties = NULL );
/** /**
* Function Load * Load information from some input file format that this #SCH_PLUGIN implementation
* * knows about, into either a new #SCH_SHEET or an existing one. This may be used to load an
* loads information from some input file format that this SCH_PLUGIN implementation * entire new #SCH_SHEET, or to augment an existing one if \a aAppendToMe is not NULL.
* knows about, into either a new SCHEMATIC or an existing one. This may be used to load an
* entire new SCHEMATIC, or to augment an existing one if @a aAppendToMe is not NULL.
* *
* @param aFileName is the name of the file to use as input 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. * nature or native in nature.
* *
* @param aAppendToMe is an existing SCHEMATIC to append to, but if NULL then this means * @param aKiway is the #KIWAY object used to access the component libraries loaded
* by the project.
*
* @param aAppendToMe is an existing #SCH_SHEET to append to, but if NULL then this means
* "do not append, rather load anew". * "do not append, rather load anew".
* *
* @param aProperties is an associative array that can be used to tell the loader how to * @param aProperties is an associative array that can be used to tell the loader how to
@ -238,8 +231,8 @@ public:
* this object (plugin may not delete it), and plugins should expect * this object (plugin may not delete it), and plugins should expect
* it to be optionally NULL. * it to be optionally NULL.
* *
* @return SCHEMATIC* - the successfully loaded schematic, or the same one as \a aAppendToMe * @return the successfully loaded schematic, or the same one as \a aAppendToMe
* if \a aAppendToMe was not NULL, and the caller owns it. * if \a aAppendToMe was not NULL, and the caller owns it.
* *
* @throw IO_ERROR if there is a problem loading, and its contents should say what went * @throw IO_ERROR if there is a problem loading, and its contents should say what went
* wrong, using line number and character offsets of the input file if * wrong, using line number and character offsets of the input file if
@ -249,19 +242,20 @@ public:
SCH_SHEET* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL ); SCH_SHEET* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL );
/** /**
* Function Save * Write \a aSchematic to a storage file in a format that this #SCH_PLUGIN implementation
* * knows about, or it can be used to write a portion of \a aSchematic to a special kind
* will write @a aSchematic to a storage file in a format that this * of export file.
* SCH_PLUGIN implementation knows about, or it can be used to write a portion of
* aSchematic to a special kind of export file.
* *
* @param aFileName is the name of a file to save to on disk. * @param aFileName is the name of a file to save to on disk.
* *
* @param aSchematic is the class SCHEMATIC in memory document tree from which to extract * @param aSchematic is the class #SCH_SCREEN in memory document tree from which to extract
* information when writing to \a aFileName. The caller continues to * information when writing to \a aFileName. The caller continues to
* own the SCHEMATIC, and the plugin should refrain from modifying the * own the SCHEMATIC, and the plugin should refrain from modifying the
* SCHEMATIC if possible. * SCHEMATIC if possible.
* *
* @param aKiway is the #KIWAY object used to access the component libraries loaded
* by the project.
*
* @param aProperties is an associative array that can be used to tell the saver how to * @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 * save the file, because it can take any number of additional named
* tuning arguments that the plugin is known to support. The caller * tuning arguments that the plugin is known to support. The caller
@ -277,16 +271,16 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function EnumerateSymbolLib * Populate a list of #LIB_PART alias names contained within the library \a aLibraryPath.
*
* returns a list of #LIB_PART alias names contained within the library @a aLibraryPath.
* *
* @param aAliasNameList is an array to populate with the #LIB_ALIAS names associated with * @param aAliasNameList is an array to populate with the #LIB_ALIAS names associated with
* the library. * the library.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, * @param aLibraryPath is a locator for the "library", usually a directory, file,
* or URL containing one or more #LIB_PART objects. * or URL containing one or more #LIB_PART objects.
*
* @param aProperties is an associative array that can be used to tell the plugin anything * @param aProperties is an associative array that can be used to tell the plugin anything
* needed about how to perform with respect to @a aLibraryPath. The * needed about how to perform with respect to \a aLibraryPath. The
* caller continues to own this object (plugin may not delete it), and * caller continues to own this object (plugin may not delete it), and
* plugins should expect it to be optionally NULL. * plugins should expect it to be optionally NULL.
* *
@ -297,16 +291,16 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function EnumerateSymbolLib * Populate a list of #LIB_PART aliases contained within the library \a aLibraryPath.
*
* returns a list of #LIB_PART aliases contained within the library @a aLibraryPath.
* *
* @param aAliasList is an array to populate with the #LIB_ALIAS pointers associated with * @param aAliasList is an array to populate with the #LIB_ALIAS pointers associated with
* the library. * the library.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, * @param aLibraryPath is a locator for the "library", usually a directory, file,
* or URL containing one or more #LIB_PART objects. * or URL containing one or more #LIB_PART objects.
*
* @param aProperties is an associative array that can be used to tell the plugin anything * @param aProperties is an associative array that can be used to tell the plugin anything
* needed about how to perform with respect to @a aLibraryPath. The * needed about how to perform with respect to \a aLibraryPath. The
* caller continues to own this object (plugin may not delete it), and * caller continues to own this object (plugin may not delete it), and
* plugins should expect it to be optionally NULL. * plugins should expect it to be optionally NULL.
* *
@ -317,10 +311,8 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function LoadSymbol * Load a #LIB_ALIAS object having \a aAliasName from the \a aLibraryPath containing
* * a library format that this #SCH_PLUGIN knows about. The #LIB_PART should be accessed
* loads a #LIB_ALIAS object having @a aAliasName from the @a aLibraryPath containing
* a library format that this SCH_PLUGIN knows about. The #LIB_PART should be accessed
* indirectly using the #LIB_ALIAS it is associated with. * indirectly using the #LIB_ALIAS it is associated with.
* *
* @param aLibraryPath is a locator for the "library", usually a directory, file, * @param aLibraryPath is a locator for the "library", usually a directory, file,
@ -335,18 +327,16 @@ public:
* (plugin may not delete it), and plugins should expect it to be * (plugin may not delete it), and plugins should expect it to be
* optionally NULL. * optionally NULL.
* *
* @return LIB_ALIAS* - if found caller shares it, else NULL if not found. * @return the alias if found caller shares it or NULL if not found.
* *
* @throw IO_ERROR if the library cannot be found or read. No exception * @throw IO_ERROR if the library cannot be found or read. No exception
* is thrown in the case where aAliasName cannot be found. * is thrown in the case where aAliasName cannot be found.
*/ */
virtual LIB_ALIAS* LoadSymbol( const wxString& aLibraryPath, const wxString& aAliasName, virtual LIB_ALIAS* LoadSymbol( const wxString& aLibraryPath, const wxString& aAliasName,
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function SaveSymbol * Write \a aSymbol to an existing library located at \a aLibraryPath. If a #LIB_PART
*
* will write @a aSymbol to an existing library located at @a aLibraryPath. If a #LIB_PART
* by the same name already exists or there are any conflicting alias names, the new * by the same name already exists or there are any conflicting alias names, the new
* #LIB_PART will silently overwrite any existing aliases and/or part becaue libraries * #LIB_PART will silently overwrite any existing aliases and/or part becaue libraries
* cannot have duplicate alias names. It is the responsibility of the caller to check * cannot have duplicate alias names. It is the responsibility of the caller to check
@ -370,11 +360,9 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function DeleteAlias * Delete \a aAliasName from the library at \a aLibraryPath.
* *
* deletes @a aAliasName from the library at @a aLibraryPath. * If \a aAliasName refers the the root #LIB_PART object, the part is renamed to
*
* If @a aAliasName refers the the root #LIB_PART object, the part is renamed to
* the next or previous #LIB_ALIAS in the #LIB_PART if one exists. If the #LIB_ALIAS * the next or previous #LIB_ALIAS in the #LIB_PART if one exists. If the #LIB_ALIAS
* is the last alias referring to the root #LIB_PART, the #LIB_PART is also removed * is the last alias referring to the root #LIB_PART, the #LIB_PART is also removed
* from the library. * from the library.
@ -396,10 +384,8 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function DeleteSymbol * Delete the entire #LIB_PART associated with \a aAliasName from the library
* * \a aLibraryPath.
* deletes the entire #LIB_PART associated with @a aAliasName from the library
* @a aLibraryPath.
* *
* @param aLibraryPath is a locator for the "library", usually a directory, file, * @param aLibraryPath is a locator for the "library", usually a directory, file,
* or URL containing several symbols. * or URL containing several symbols.
@ -419,9 +405,7 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function CreateSymbolLib * Create a new empty symbol library at \a aLibraryPath. It is an error to attempt
*
* creates a new empty symbol library at @a aLibraryPath. It is an error to attempt
* to create an existing library or to attempt to create on a "read only" location. * 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, file, * @param aLibraryPath is a locator for the "library", usually a directory, file,
@ -439,9 +423,7 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function DeleteSymbolLib * Delete an existing symbol library and returns true if successful, or if library
*
* deletes an existing symbol library and returns true if successful, or if library
* does not exist returns false, or throws an exception if library exists but is read * does not exist returns false, or throws an exception if library exists but is read
* only or cannot be deleted for some other reason. * only or cannot be deleted for some other reason.
* *
@ -455,7 +437,7 @@ public:
* object (plugin may not delete it), and plugins should expect * object (plugin may not delete it), and plugins should expect
* it to be optionally NULL. * it to be optionally NULL.
* *
* @return bool - true if library deleted, false if library did not exist. * @return true if library deleted or false if library did not exist.
* *
* @throw IO_ERROR if there is a problem deleting an existing library. * @throw IO_ERROR if there is a problem deleting an existing library.
*/ */
@ -463,8 +445,7 @@ public:
const PROPERTIES* aProperties = NULL ); const PROPERTIES* aProperties = NULL );
/** /**
* Function IsSymbolLibWritable * Return true if the library at \a aLibraryPath is writable. (Often
* returns true if the library at @a aLibraryPath is writable. (Often
* system libraries are read only because of where they are installed.) * system libraries are read only because of where they are installed.)
* *
* @param aLibraryPath is a locator for the "library", usually a directory, file, * @param aLibraryPath is a locator for the "library", usually a directory, file,
@ -475,9 +456,7 @@ public:
virtual bool IsSymbolLibWritable( const wxString& aLibraryPath ); virtual bool IsSymbolLibWritable( const wxString& aLibraryPath );
/** /**
* Function SymbolLibOptions * Append supported #SCH_PLUGIN options to \a aListToAppenTo along with internationalized
*
* appends supported SCH_PLUGIN options to @a aListToAppenTo along with internationalized
* descriptions. Options are typically appended so that a derived SCH_PLUGIN can call * descriptions. Options are typically appended so that a derived SCH_PLUGIN can call
* its base class function by the same name first, thus inheriting options declared there. * its base class function by the same name first, thus inheriting options declared there.
* (Some base class options could pertain to all Symbol*() functions in all derived * (Some base class options could pertain to all Symbol*() functions in all derived
@ -494,11 +473,11 @@ public:
* It may be multi-line and be quite explanatory of the option.</dd> * It may be multi-line and be quite explanatory of the option.</dd>
* </dl> * </dl>
* <br> * <br>
* In the future perhaps @a aListToAppendTo evolves to something capable of also * In the future perhaps \a aListToAppendTo evolves to something capable of also
* holding a wxValidator for the cells in said dialog: * holding a wxValidator for the cells in said dialog:
* http://forums.wxwidgets.org/viewtopic.php?t=23277&p=104180. * http://forums.wxwidgets.org/viewtopic.php?t=23277&p=104180.
* This would require a 3 column list, and introducing wx GUI knowledge to * This would require a 3 column list, and introducing wx GUI knowledge to
* SCH_PLUGIN, which has been avoided to date. * #SCH_PLUGIN, which has been avoided to date.
*/ */
virtual void SymbolLibOptions( PROPERTIES* aListToAppendTo ) const; virtual void SymbolLibOptions( PROPERTIES* aListToAppendTo ) const;
@ -516,10 +495,8 @@ public:
/** /**
* Class SCH_PLUGIN_RELEASER * Helper object to release a #SCH_PLUGIN in the context of a potential thrown exception
* * through its destructor.
* releases a SCH_PLUGIN in the context of a potential thrown exception, through
* its destructor.
*/ */
class SCH_PLUGIN_RELEASER class SCH_PLUGIN_RELEASER
{ {

4
eeschema/schframe.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2015 Jean-Pierre Charras, jp.charras wanadoo.fr * Copyright (C) 2015 Jean-Pierre Charras, jp.charras wanadoo.fr
* Copyright (C) 2008-2015 Wayne Stambaugh <stambaughw@verizon.net> * Copyright (C) 2008-2017 Wayne Stambaugh <stambaughw@verizon.net>
* Copyright (C) 2004-2017 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2004-2017 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
@ -1089,7 +1089,7 @@ private:
* else search in all loaded libs * else search in all loaded libs
* *
* @param aDC is the device context to draw upon. * @param aDC is the device context to draw upon.
* @param aFilters is a filter to pass the allowed lib names list, or library name * @param aFilter is a filter to pass the allowed lib names list, or library name
* to load the component from and/or some other filters * to load the component from and/or some other filters
* if NULL, no filtering. * if NULL, no filtering.
* @param aHistoryList list remembering recently used component names. * @param aHistoryList list remembering recently used component names.

30
include/plot_common.h
View File

@ -2,7 +2,7 @@
* This program source code file is part of KiCad, a free EDA CAD application. * This program source code file is part of KiCad, a free EDA CAD application.
* *
* Copyright (C) 2016 Jean-Pierre Charras, jp.charras at wanadoo.fr * Copyright (C) 2016 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2016-2017 KiCad Developers, see AUTHORS.txt for contributors.
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
@ -322,8 +322,8 @@ public:
* virtual function FlashPadRoundRect * virtual function FlashPadRoundRect
* @param aPadPos Position of the shape (center of the rectangle * @param aPadPos Position of the shape (center of the rectangle
* @param aSize = size of rounded rect * @param aSize = size of rounded rect
* @param aCornerRadius = radius of the rounded corners * @param aCornerRadius Radius of the rounded corners
* @param aOrient is the rotation of the shape * @param aOrient The rotation of the shape
* @param aTraceMode FILLED or SKETCH * @param aTraceMode FILLED or SKETCH
* @param aData an auxiliary info (mainly for gerber format attributes) * @param aData an auxiliary info (mainly for gerber format attributes)
*/ */
@ -607,13 +607,12 @@ public:
virtual void Arc( const wxPoint& centre, double StAngle, double EndAngle, virtual void Arc( const wxPoint& centre, double StAngle, double EndAngle,
int rayon, FILL_T fill, int width = USE_DEFAULT_LINE_WIDTH ) override; int rayon, FILL_T fill, int width = USE_DEFAULT_LINE_WIDTH ) override;
virtual void PenTo( const wxPoint& pos, char plume ) override; virtual void PenTo( const wxPoint& pos, char plume ) override;
virtual void FlashPadCircle( const wxPoint& pos, int diametre, virtual void FlashPadCircle( const wxPoint& aPadPos, int aDiameter,
EDA_DRAW_MODE_T trace_mode, void* aData ) override; EDA_DRAW_MODE_T aTraceMode, void* aData ) override;
virtual void FlashPadOval( const wxPoint& pos, const wxSize& size, double orient, virtual void FlashPadOval( const wxPoint& aPadPos, const wxSize& aSize, double aPadOrient,
EDA_DRAW_MODE_T trace_mode, void* aData ) override; EDA_DRAW_MODE_T aTraceMode, void* aData ) override;
virtual void FlashPadRect( const wxPoint& aPadPos, const wxSize& aSize, virtual void FlashPadRect( const wxPoint& aPadPos, const wxSize& aSize,
double aPadOrient, EDA_DRAW_MODE_T aTraceMode, double aOrient, EDA_DRAW_MODE_T aTraceMode, void* aData ) override;
void* aData ) override;
virtual void FlashPadRoundRect( const wxPoint& aPadPos, const wxSize& aSize, virtual void FlashPadRoundRect( const wxPoint& aPadPos, const wxSize& aSize,
int aCornerRadius, double aOrient, int aCornerRadius, double aOrient,
EDA_DRAW_MODE_T aTraceMode, void* aData ) override; EDA_DRAW_MODE_T aTraceMode, void* aData ) override;
@ -666,12 +665,13 @@ public:
} }
// Pad routines are handled with lower level primitives // Pad routines are handled with lower level primitives
virtual void FlashPadCircle( const wxPoint& pos, int diametre, virtual void FlashPadCircle( const wxPoint& aPadPos, int aDiameter,
EDA_DRAW_MODE_T trace_mode, void* aData ) override; EDA_DRAW_MODE_T aTraceMode, void* aData ) override;
virtual void FlashPadOval( const wxPoint& pos, const wxSize& size, double orient, virtual void FlashPadOval( const wxPoint& aPadPos, const wxSize& aSize, double aPadOrient,
EDA_DRAW_MODE_T trace_mode, void* aData ) override; EDA_DRAW_MODE_T aTraceMode, void* aData ) override;
virtual void FlashPadRect( const wxPoint& pos, const wxSize& size, virtual void FlashPadRect( const wxPoint& aPadPos, const wxSize& aSize,
double orient, EDA_DRAW_MODE_T trace_mode, void* aData ) override; double aPadOrient, EDA_DRAW_MODE_T aTraceMode,
void* aData ) override;
virtual void FlashPadRoundRect( const wxPoint& aPadPos, const wxSize& aSize, virtual void FlashPadRoundRect( const wxPoint& aPadPos, const wxSize& aSize,
int aCornerRadius, double aOrient, int aCornerRadius, double aOrient,
EDA_DRAW_MODE_T aTraceMode, void* aData ) override; EDA_DRAW_MODE_T aTraceMode, void* aData ) override;

4
include/wxPcbStruct.h
View File

@ -618,8 +618,8 @@ public:
* Function SetElementVisibility * Function SetElementVisibility
* changes the visibility of an element category * changes the visibility of an element category
* @param aElement is from the enum by the same name * @param aElement is from the enum by the same name
* @see enum GAL_LAYER_ID * @param aNewState The new visibility state of the element category
* @param aNewState = The new visibility state of the element category * @see enum PCB_LAYER_ID
*/ */
void SetElementVisibility( GAL_LAYER_ID aElement, bool aNewState ); void SetElementVisibility( GAL_LAYER_ID aElement, bool aNewState );