110 lines
9.0 KiB
XML
110 lines
9.0 KiB
XML
<?xml version='1.0' encoding='UTF-8' standalone='no'?>
|
|
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.9.1" xml:lang="en-US">
|
|
<compounddef id="group__Generalities" kind="group">
|
|
<compoundname>Generalities</compoundname>
|
|
<title>Generalities</title>
|
|
<briefdescription>
|
|
<para>The supporting paraphernalia. </para>
|
|
</briefdescription>
|
|
<detaileddescription>
|
|
<sect1 id="group__Generalities_1secGeneralitiesIntro">
|
|
<title>Introduction</title>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
</sect1>
|
|
<sect1 id="group__Generalities_1secGeneralitiesNammingConventions">
|
|
<title>Namming conventions</title>
|
|
<para>The name of "C macros" are written with lower case letters and underscores (examples : <bold>is_a</bold>, <bold>for_each_cell</bold> or <bold>end_for</bold>) while the name of generic functions and member functions never use the underscore and always start with an Upper case letter (examples : <bold>GetUnit</bold>, <bold>GetMasterCell</bold>, <bold>IsCalledBy</bold>).</para>
|
|
<para><simplesect kind="remark"><para>When examining <computeroutput></computeroutput>.h include files for more detailed information you will find member functions which start with an underscore. <bold>While being "public" those functions must never be called upon</bold>. In principle, only here'after documented functions should be used by the application programmer.</para>
|
|
</simplesect>
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="group__Generalities_1secGeneralitiesGetString">
|
|
<title>GetString</title>
|
|
<para><programlisting><codeline><highlight class="normal">string<sp/>GetString(const<sp/>Object&<sp/>object);</highlight></codeline>
|
|
<codeline><highlight class="normal">string<sp/>GetString(const<sp/>Object*<sp/>object);</highlight></codeline>
|
|
</programlisting> Thoses generic function allows you to get into a string an explicit description of any kind of <ref refid="namespaceHurricane" kindref="compound">Hurricane</ref> object pointer or reference. <programlisting><codeline><highlight class="normal">ostream&<sp/>operator<<<sp/>(ostream&<sp/>stream,<sp/>const<sp/>Object&<sp/>object);</highlight></codeline>
|
|
<codeline><highlight class="normal">ostream&<sp/>operator<<<sp/>(ostream&<sp/>stream,<sp/>const<sp/>Object*<sp/>object);</highlight></codeline>
|
|
</programlisting> All <ref refid="namespaceHurricane" kindref="compound">Hurricane</ref> objects have printing operators for a reference or a pointer. Those printing operators use the generic function Hurricane::GetString() previously studied.</para>
|
|
</sect1>
|
|
<sect1 id="group__Generalities_1secGeneralitiesPredicates">
|
|
<title>Predicates</title>
|
|
<para>The <computeroutput>bool</computeroutput> <computeroutput>is_a<Type*>(object)</computeroutput> function.</para>
|
|
<para>For any kind of <ref refid="namespaceHurricane" kindref="compound">Hurricane</ref> 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 <computeroutput><type></computeroutput> as shown in the following example: <programlisting><codeline><highlight class="normal">DataBase*<sp/>dataBase<sp/>=<sp/>GetDataBase();</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal">Library*<sp/>library<sp/>=<sp/>Library::Create(dataBase,<sp/>"std");</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal">Cell*<sp/>cell<sp/>=<sp/>Cell::Create(library,<sp/>"nand");</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal">if<sp/>(is_a<Cell*>(cell))<sp/>{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>//<sp/>will<sp/>inevitably<sp/>go<sp/>through<sp/>here</highlight></codeline>
|
|
<codeline><highlight class="normal">}</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal">if<sp/>(is_a<Entity*>(cell))<sp/>{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>//<sp/>will<sp/>go<sp/>through<sp/>here<sp/>also<sp/>because<sp/>Cell<sp/>derives<sp/>from<sp/>Entity</highlight></codeline>
|
|
<codeline><highlight class="normal">}</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal">if<sp/>(is_a<Library*>(cell))<sp/>{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>//<sp/>will<sp/>never<sp/>go<sp/>through<sp/>here<sp/>because<sp/>Cell<sp/>doesn't<sp/>derive<sp/>from<sp/>Library</highlight></codeline>
|
|
<codeline><highlight class="normal">}</highlight></codeline>
|
|
</programlisting></para>
|
|
</sect1>
|
|
<sect1 id="group__Generalities_1secGeneralitiesInheritance">
|
|
<title>Inheritance</title>
|
|
<para>All classes deriving directly from a base class define a new type named <bold>Inherit</bold> which represents this base class. <bold>This one is unique because <ref refid="namespaceHurricane" kindref="compound">Hurricane</ref> doesn't use multiple inheritance</bold>. 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: <programlisting><codeline><highlight class="normal">void<sp/>MyObject::Draw()<sp/>const</highlight></codeline>
|
|
<codeline><highlight class="normal">//<sp/>************************</highlight></codeline>
|
|
<codeline><highlight class="normal">{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>Inherit::Draw();</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>DrawParticularities();</highlight></codeline>
|
|
<codeline><highlight class="normal">}</highlight></codeline>
|
|
</programlisting></para>
|
|
</sect1>
|
|
<sect1 id="group__Generalities_1secGeneralitiesTraceUtilities">
|
|
<title>Trace utilities</title>
|
|
<para>The library provides some usefull utilities for generating trace printings with a natural indentation allowing better understanding of the processing sequences:</para>
|
|
<para><itemizedlist>
|
|
<listitem>
|
|
<para><bold>Hurricane::in_trace</bold> </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><bold>Hurricane::trace_on</bold> </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><bold>Hurricane::trace_off</bold> </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><bold>Hurricane::trace_in</bold> </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><bold>Hurricane::trace_out</bold> </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><bold>Hurricane::trace</bold> </para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para><programlisting><codeline><highlight class="normal">void<sp/>MyFunction(MyData*<sp/>data)</highlight></codeline>
|
|
<codeline><highlight class="normal">//<sp/>**************************</highlight></codeline>
|
|
<codeline><highlight class="normal">{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>trace<sp/><<<sp/>"entering<sp/>in<sp/>MyFunction<sp/>with<sp/>"<sp/><<<sp/>data<sp/><<<sp/>endl;</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>trace_in();</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>...</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/></highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>trace<sp/><<<sp/>"exiting<sp/>of<sp/>MyFunction"<sp/><<<sp/>endl;</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/>trace_out();</highlight></codeline>
|
|
<codeline><highlight class="normal">}</highlight></codeline>
|
|
</programlisting> <simplesect kind="remark"><para>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...</para>
|
|
</simplesect>
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="group__Generalities_1secGeneralitiesRemarks">
|
|
<title>Remarks</title>
|
|
<para>Many other global and generic functions exist. Each one will be studied within the description of the classes which create or specialize them (example: <bold>Hurricane::GetUnit</bold> will be introduced with the Unit class and <bold>Hurricane::GetCollection</bold> with the <ref refid="classHurricane_1_1Collection" kindref="compound">Collection</ref> class). </para>
|
|
</sect1>
|
|
</detaileddescription>
|
|
</compounddef>
|
|
</doxygen>
|