193 lines
6.7 KiB
C++
193 lines
6.7 KiB
C++
|
|
// -*- C++ -*-
|
|
|
|
|
|
namespace Hurricane {
|
|
|
|
/*! \defgroup Generalities Generalities
|
|
* \brief The supporting paraphernalia.
|
|
*
|
|
* \section secGeneralitiesIntro Introduction
|
|
*
|
|
* When documenting a given class, only member functions
|
|
* introducted by this class are documented, inherited ones are
|
|
* not repeated. This is made easier by the presence of the
|
|
* inheritance sub-tree containing the described object type.
|
|
*
|
|
* In the same way, some opetators or global functions are
|
|
* defined for all object types though they don't derive from a
|
|
* common base class. Those operators and generic functions will
|
|
* be described below.
|
|
*
|
|
* terminology In the following, we will describe operators and
|
|
* functions applying to objects of different types. Therefore
|
|
* we will name "Object" any of those types.
|
|
*
|
|
*
|
|
* \section secGeneralitiesNammingConventions Namming conventions
|
|
*
|
|
* The name of "C macros" are written with lower case letters
|
|
* and underscores (examples : <b>is_a</b>, <b>for_each_cell</b>
|
|
* or <b>end_for</b>) while the name of generic functions and
|
|
* member functions never use the underscore and always start
|
|
* with an Upper case letter (examples : <b>GetUnit</b>,
|
|
* <b>GetMasterCell</b>, <b>IsCalledBy</b>).
|
|
*
|
|
* \remark When examining \c .h include files for more detailed information
|
|
* you will find member functions which start with an
|
|
* underscore. <b>While being "public" those functions must
|
|
* never be called upon</b>. In principle, only here'after
|
|
* documented functions should be used by the application
|
|
* programmer.
|
|
*
|
|
*
|
|
* \section secGeneralitiesGetString GetString
|
|
*
|
|
\code
|
|
string GetString(const Object& object);
|
|
string GetString(const Object* object);
|
|
\endcode
|
|
* Thoses generic function allows you to get into a string an
|
|
* explicit description of any kind of Hurricane object pointer
|
|
* or reference.
|
|
\code
|
|
ostream& operator<< (ostream& stream, const Object& object);
|
|
ostream& operator<< (ostream& stream, const Object* object);
|
|
\endcode
|
|
* All Hurricane objects have printing operators for a reference
|
|
* or a pointer. Those printing operators use the generic
|
|
* function Hurricane::GetString() previously studied.
|
|
*
|
|
*
|
|
* \section secGeneralitiesPredicates Predicates
|
|
*
|
|
* The \c bool \c is_a<Type*>(object) function.
|
|
*
|
|
* For any kind of Hurricane object pertaining to a
|
|
* class with at least one "virtual" member, it is
|
|
* possible to determine if this object is a type or a
|
|
* sub-type of \c \<type\> as shown in the following
|
|
* example:
|
|
\code
|
|
DataBase* dataBase = GetDataBase();
|
|
|
|
Library* library = Library::Create(dataBase, "std");
|
|
|
|
Cell* cell = Cell::Create(library, "nand");
|
|
|
|
if (is_a<Cell*>(cell)) {
|
|
// will inevitably go through here
|
|
}
|
|
|
|
if (is_a<Entity*>(cell)) {
|
|
// will go through here also because Cell derives from Entity
|
|
}
|
|
|
|
if (is_a<Library*>(cell)) {
|
|
// will never go through here because Cell doesn't derive from Library
|
|
}
|
|
\endcode
|
|
*
|
|
*
|
|
* \section secGeneralitiesInheritance Inheritance
|
|
*
|
|
* All classes deriving directly from a base class define a new
|
|
* type named <b>Inherit</b> which represents this base class.
|
|
* <b>This one is unique because Hurricane doesn't use multiple
|
|
* inheritance</b>. This type is important because it allows to
|
|
* call upon the methods of the base class without knowing its
|
|
* name as shown in the following example:
|
|
\code
|
|
void MyObject::Draw() const
|
|
// ************************
|
|
{
|
|
Inherit::Draw();
|
|
|
|
DrawParticularities();
|
|
}
|
|
\endcode
|
|
*
|
|
*
|
|
* \section secGeneralitiesTraceUtilities Trace utilities
|
|
*
|
|
* The library provides some usefull utilities for generating
|
|
* trace printings with a natural indentation allowing better
|
|
* understanding of the processing sequences:
|
|
*
|
|
* <ul>
|
|
* <li><b>Hurricane::in_trace</b>
|
|
* <li><b>Hurricane::trace_on</b>
|
|
* <li><b>Hurricane::trace_off</b>
|
|
* <li><b>Hurricane::trace_in</b>
|
|
* <li><b>Hurricane::trace_out</b>
|
|
* <li><b>Hurricane::trace</b>
|
|
* </ul>
|
|
*
|
|
*
|
|
\code
|
|
void MyFunction(MyData* data)
|
|
// **************************
|
|
{
|
|
trace << "entering in MyFunction with " << data << endl;
|
|
trace_in();
|
|
|
|
...
|
|
|
|
trace << "exiting of MyFunction" << endl;
|
|
trace_out();
|
|
}
|
|
\endcode
|
|
* \remark Debugger enthousiastic users will probably ignore this trace
|
|
* capability which presents the annoying need to be inserted
|
|
* into the code... For myself, I do prefer those facilities...
|
|
*
|
|
*
|
|
* \section secGeneralitiesRemarks Remarks
|
|
*
|
|
* Many other global and generic functions exist. Each one will
|
|
* be studied within the description of the classes which create
|
|
* or specialize them (example: <b>Hurricane::GetUnit</b> will be
|
|
* introduced with the Unit class and <b>Hurricane::GetCollection</b> with
|
|
* the Collection class).
|
|
*/
|
|
|
|
|
|
|
|
/*! \addtogroup Generalities
|
|
*/
|
|
// \{
|
|
|
|
/*! \function bool in_trace();
|
|
* The trace being optional, this function informs wether the
|
|
* trace is active or not. This allows if necessary to execute
|
|
* additional operations.
|
|
*/
|
|
|
|
/*! \function void trace_on();
|
|
* Activates the trace.
|
|
*/
|
|
|
|
/*! \function void trace_off();
|
|
* Suspends the trace.
|
|
*/
|
|
|
|
/*! \function void trace_in();
|
|
* Allows to enter a new trace block. This appears visually by
|
|
* adding an identation level to the trace printing.
|
|
*/
|
|
|
|
/*! \function void trace_out();
|
|
* Allows to leave the current trace block. This decreases the
|
|
* level of indentation of the trace print.
|
|
*/
|
|
|
|
/*! \def trace
|
|
* To be used like a <b>cerr</b> or
|
|
* a <b>cout</b> but the trace printing will be effective and
|
|
* indented only when the trace is active.
|
|
*/
|
|
|
|
// \}
|
|
|
|
}
|