From e243149f61b4d32b7735f2bdfbe1329f0c8de96b Mon Sep 17 00:00:00 2001 From: "DrZiplok@gmail.com" Date: Mon, 10 Jan 2011 01:43:41 +0000 Subject: [PATCH] Add more documentation for AP_MetaClass. git-svn-id: https://arducopter.googlecode.com/svn/trunk@1465 f9c3cf11-9bcb-44bc-f272-b75c42450872 --- libraries/AP_Common/AP_MetaClass.h | 94 ++++++++++++++++++++++-------- libraries/AP_Common/AP_Var.h | 7 +++ 2 files changed, 77 insertions(+), 24 deletions(-) diff --git a/libraries/AP_Common/AP_MetaClass.h b/libraries/AP_Common/AP_MetaClass.h index b1a96fa15e..c6915a79e4 100644 --- a/libraries/AP_Common/AP_MetaClass.h +++ b/libraries/AP_Common/AP_MetaClass.h @@ -7,9 +7,15 @@ // /// @file AP_MetaClass.h -/// Abstract meta-class from which other AP classes may inherit. -/// Provides type introspection and some basic protocols that can -/// be implemented by subclasses. +/// @brief An abstract base class from which other classes can inherit. +/// +/// This abstract base class declares and implements functions that are +/// useful to code that wants to know things about a class, or to operate +/// on the class without knowing precisely what it is. +/// +/// All classes that inherit from this class can be assumed to have these +/// basic functions. +/// #ifndef AP_METACLASS_H #define AP_METACLASS_H @@ -29,21 +35,39 @@ public: /// Default constructor does nothing. AP_MetaClass(void); - /// Default destructor is virtual, to ensure that all destructors - /// are called for derived classes. + /// Default destructor is virtual, to ensure that all subclasses' + /// destructors are virtual. This guarantees that all destructors + /// in the inheritance chain are called at destruction time. + /// virtual ~AP_MetaClass(); - /// Type code, unique to all instances of a given subclass. + /// Typedef for the ID unique to all instances of a class. + /// + /// See ::meta_type_id for a discussion of class type IDs. + /// typedef uint16_t AP_TypeID; /// Obtain a value unique to all instances of a specific subclass. /// + /// The value can be used to determine whether two class pointers + /// refer to the same exact class type. The value can also be cached + /// and then used to detect objects of a given type at a later point. + /// /// This is similar to the basic functionality of the C++ typeid /// keyword, but does not depend on std::type_info or any compiler- /// generated RTTI. /// - /// As the value is derived from the vtable address, it cannot be - /// introspected outside the current state of the system. + /// The value is derived from the vtable address, so it is guaranteed + /// to be unique but cannot be known until the program has been compiled + /// and linked. Thus, the only way to know the type ID of a given + /// type is to construct an object at runtime. To cache the type ID + /// of a class Foo, one would write: + /// + /// AP_MetaClass::AP_TypeID Foo_type_id; + /// + /// { Foo a; Foo_type_id = a.meta_type_id(); } + /// + /// This will construct a temporary Foo object a and save its type ID. /// /// @param p A pointer to an instance of a subclass of AP_MetaClass. /// @return A type-unique value. @@ -56,6 +80,10 @@ public: /// enough information to construct and validate a pointer to the instance /// when passed back from an untrusted source. /// + /// Handles are useful when passing a reference to an object to a client outside + /// the system, as they can be validated by the system when the client hands + /// them back. + /// typedef uint32_t AP_MetaHandle; /// Return a value that can be used as an external pointer to an instance @@ -111,9 +139,17 @@ public: /// Tests whether two objects are of precisely the same class. /// - /// Note that for p2 inheriting from p1, this will return false. - /// Even with RTTI not disabled, there does not seem to be enough information - /// to determine whether one class inherits from another. + /// Note that in the case where p2 inherits from p1, or vice-versa, this will return + /// false as we cannot detect these inheritance relationships at runtime. + /// + /// In the caller's context, p1 and p2 may be pointers to any type, but we require + /// that they be passed as pointers to AP_MetaClass in order to make it clear that + /// they should be pointers to classes derived from AP_MetaClass. + /// + /// No attempt is made to validate whether p1 and p2 are actually derived from + /// AP_MetaClass. If p1 and p2 are equal, or if they point to non-class objects with + /// similar contents, or to non-AP_MetaClass derived classes with no virtual functions + /// this function may return true. /// /// @param p1 The first object to be compared. /// @param p2 The second object to be compared. @@ -124,7 +160,11 @@ public: return p1->meta_type_id() == p2->meta_type_id(); } - /// Cast an object to an expected class type. + /// Cast a pointer to an expected class type. + /// + /// This function is used when a pointer is expected to be a pointer to a + /// subclass of AP_MetaClass, but the caller is not certain. It will return the pointer + /// if it is, or NULL if it is not a pointer to the expected class. /// /// This should be used with caution, as _typename's default constructor and /// destructor will be run, possibly introducing undesired side-effects. @@ -146,36 +186,42 @@ public: return NULL; } - /// Serialise the class. + /// Serialize the class. /// - /// Serialisation provides a mechanism for exporting the state of the class to an + /// Serialization stores the state of the class in an external buffer in such a + /// fashion that it can later be restored by unserialization. + /// + /// AP_MetaClass subclasses should only implement these functions if saving and + /// restoring their state makes sense. + /// + /// Serialization provides a mechanism for exporting the state of the class to an /// external consumer, either for external introspection or for subsequent restoration. /// - /// Classes that wrap variables should define the format of their serialised data + /// Classes that wrap variables should define the format of their serialiaed data /// so that external consumers can reliably interpret it. /// /// @param buf Buffer into which serialised data should be placed. /// @param bufSize The size of the buffer provided. /// @return The size of the serialised data, even if that data would /// have overflowed the buffer. If the return value is zero, - /// the class does not support serialisation. + /// the class does not support serialization. /// virtual size_t serialize(void *buf, size_t bufSize) const; - /// Unserialise the class. + /// Unserialize the class. /// - /// Unserialising a class from a buffer into which the class previously serialised - /// itself restores the instance to an identical state, where "identical" may be - /// defined in context. + /// Unserializing a class from a buffer into which the class previously serialized + /// itself restores the instance to an identical state, where "identical" is left + /// up to the class itself to define. /// - /// Classes that wrap variables should define the format of their serialised data so + /// Classes that wrap variables should define the format of their serialized data so /// that external providers can reliably encode it. /// - /// @param buf Buffer containing serialised data. + /// @param buf Buffer containing serialized data. /// @param bufSize The size of the buffer. /// @return The number of bytes from the buffer that would be consumed - /// unserialising the data. If the value is less than or equal - /// to bufSize, unserialisation was successful. If the return + /// unserializing the data. If the value is less than or equal + /// to bufSize, unserialization was successful. If the return /// value is zero the class does not support unserialisation or /// the data in the buffer is invalid. /// diff --git a/libraries/AP_Common/AP_Var.h b/libraries/AP_Common/AP_Var.h index 6a152058f8..3b829d33a9 100644 --- a/libraries/AP_Common/AP_Var.h +++ b/libraries/AP_Common/AP_Var.h @@ -5,6 +5,13 @@ // Free Software Foundation; either version 2.1 of the License, or (at // your option) any later version. // + +/// @file AP_Var.h +/// @brief A system for managing and storing variables that are of +/// general interest to the system. +/// +/// + /// The AP variable interface. This allows different types /// of variables to be passed to blocks for floating point /// math, memory management, etc.