Changeset 219 for trunk/nom/idl


Ignore:
Timestamp:
Feb 3, 2007, 6:59:37 PM (19 years ago)
Author:
cinc
Message:

Added doxygen tags. Some minor changes to NOMClass.

Location:
trunk/nom/idl
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/nom/idl/nomcls.idl

    r179 r219  
    4444  NOMCLASSVERSION(1, 0 );
    4545
    46   Object nomNew();
     46  /**
     47    This method is called to create an object of the class this metaclass
     48    is the class object for.
     49    The method uses nomAllocate() to get the amount of storage necessary to
     50    hold one instance of the object to be built. When successful nomRenew()
     51    is called with the allocated storage block to initalize the object.
     52
     53    \sa nomRenew(), nomRenewNoInit(), impl_NOMClass_nomNew()
     54   */
     55  PNOMObject nomNew();
     56
     57  /**
     58     This method returns the name of the class this class object is an instance of.
     59
     60     \par How to override
     61     This method is usually not overriden.
     62
     63     \sa impl_NOMClass_nomGetName()
     64   */
    4765  string nomGetName();
    48   Object nomRenew(in Object nomObj);
    49   Object nomRenewNoInit(in Object nomObj);
    5066
    51   string nomAllocate(in long size);
    52   void nomDeallocate(in string memptr);
     67  /**
     68     This method is called for example by nomNew() when creating a new object. It may be
     69     used to create an object from a given memory block. If doing so be sure the storage
     70     area is big enough to hold an objects instance.
     71 
     72     The method first calls nomRenewNoInit() to set important object info on the memory block
     73     and then calls nomInit() on the newly created object.
     74
     75     \par How to override
     76     This method is usually not overriden.
     77     
     78     \sa nomNew, nomRenewNoInit(), impl_NOMClass_nomRenew()
     79   */
     80  PNOMObject nomRenew(in gpointer nomObj);
     81
     82  /**
     83     Most of object creation is done in this method which is indirectly called by nomNew().
     84     The block of storage given to the method is set to zero first. Setting the pointer to the
     85     mtab actually makes an object from the memory.
     86     If the class this object is an instance of (or any of the parent classes) did override
     87     nomUnInit() the object is registered for finalization with the garbage collector. By doing
     88     so it is ensured that nomUnInit() is called on the object when it's collected eventually.
     89
     90     This method can be used to create an object from any block of memory. It may be faster
     91     creating numerous objects from one huge memory area than calling nomNew() for every single
     92     object.
     93
     94     \remark This method does not call nomInit() on the new object. It is guaranteed that this
     95     method is always called during object creation.
     96
     97     \par How to override
     98     This method can be overriden to track the creation of objects. When doing so
     99     the parent should be called first.
     100
     101     \sa nomNew, nomRenew(), impl_NOMClass_nomRenewNoInit()
     102   */
     103  PNOMObject nomRenewNoInit(in gpointer nomObj);
     104
     105  /**
     106     Allocate size bytes for using when creating objects.
     107
     108     This method uses NOMMalloc() to allocate the memory. Because NOMMalloc() is just a wrapper
     109     around g_malloc() which is replaced by a garbage collected memory allocation routine the returned block of
     110     memory is zeroed similar to using NOMCalloc().
     111
     112     \par How to override
     113     This method is usually not overriden.
     114     
     115     \sa impl_NOMClass_nomAllocate()
     116   */
     117  gpointer nomAllocate(in long size);
     118
     119  /**
     120     Free a block of memory allocated using nomAllocate(). Because NOM is using a garbage collector
     121     this method does nothing. It's for compatibility with ported code.
     122
     123     \par How to override
     124     This method is usually not overriden.
     125 
     126     \sa impl_NOMClass_nomDeallocate()
     127   */
     128  void nomDeallocate(in gpointer memptr);
    53129  void nomSetObjectCreateInfo(in gpointer ncpObject);
    54130  gpointer nomGetObjectCreateInfo();
     131
     132  /**
     133     This method is called after the class object is built. It registers the new
     134     class with the NOMClassMagrObj.
     135     In addition to registering the class object the class this metaclass can create will
     136     also be registered.
     137
     138     \sa impl_NOMClass_nomClassReady()
     139   */
    55140  void nomClassReady();
    56141

  • trunk/nom/idl/nomobj.idl

    r210 r219  
    4444  NOMCLASSVERSION(1, 0 );
    4545
     46  /**
     47     This method is intended to be overriden by classes which need some initialization.
     48
     49     \par How to override
     50     The parent class must always be called first when overriden.
     51
     52     \sa impl_NOMObject_nomInit()
     53   */
    4654  void nomInit();
     55
     56  /**
     57     This method is intended to be overriden by classes which need some uninitialization.
     58     Note that when overriding the method the garbage collector will add the object
     59     to the list of objects with a finalizer. The finalizer will be run when the object is
     60     collected and calls nomUnInit() to give the object a chance for cleanup.
     61
     62     \note It's not necessary to free memory in nomUnInit(). This is the job of the garbage collector.
     63     Only system resources like file handles etc. must be explicitely freed.
     64
     65     \par How to override
     66     The parent method must be called after doing the own processing.
     67
     68     \sa impl_NOMObject_nomUnInit()
     69   */
    4770  void nomUnInit();
    48   /* Return the size of the object. That is sizeof(mTab*)+sizeof(all instance vars) */
     71
     72  /**
     73     Return the size of the object. That is sizeof(mTab*)+sizeof(all instance vars)
     74
     75     \par How to override
     76     This method is usually not overriden.
     77
     78     \sa impl_NOMObject_nomGetSize()
     79  */
    4980  long nomGetSize();
     81
     82  /**
     83     This method calls nomUnInit() to give the object a chance of freeing system resources.
     84     Afterwards the memory occupied by the object is given back to the system and the
     85     object is not accessible anymore.
     86
     87     \sa impl_NOMObject_delete()
     88   */
    5089  void delete();
     90
     91  /**
     92     This method returns a pointer to the class object of this object.
     93
     94     \par How to override
     95     This method is usually not overriden.
     96
     97     \return Pointer to the class object
     98
     99     \sa impl_NOMObject_nomGetClass()
     100   */
    51101  PNOMClass nomGetClass();
     102
     103  /**
     104     Create a new class of the kind the caller is. This method ensures that subclasses
     105     are properly handled without the need to override this method in every subclass.
     106
     107     This method will get the class object of nomSelf and call nomNew() on it creating
     108     a new object which has exactly the same class hierarchy of nomSelf.
     109
     110     \par How to override
     111     This method is usually not overriden.
     112
     113     \return Pointer to a new object of the same kind as nomSelf. Note that this won't
     114     create an exact copy but a completely new objecct.
     115
     116     \sa impl_NOMObject_new()
     117   */
    52118  PNOMObject new();
    53 #if 0
    54         NOMOVERRIDE(wpEchoString);
    55         NOMINSTANCEVAR(long theLong);
    56 #endif
    57119};
    58120
Note: See TracChangeset for help on using the changeset viewer.