From: JINMEI Tatuya Date: Sat, 1 Dec 2012 04:17:23 +0000 (-0800) Subject: [2382] documentation updates X-Git-Tag: bind10-1.0.0-beta-release~44^2~6 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=dfd0dd105b4fc8054e3b9cfd1bc5547302f54578;p=thirdparty%2Fkea.git [2382] documentation updates --- diff --git a/src/lib/dns/rdata.h b/src/lib/dns/rdata.h index e7811c9510..186ace2cc3 100644 --- a/src/lib/dns/rdata.h +++ b/src/lib/dns/rdata.h @@ -485,8 +485,47 @@ RdataPtr createRdata(const RRType& rrtype, const RRClass& rrclass, RdataPtr createRdata(const RRType& rrtype, const RRClass& rrclass, const Rdata& source); -/// \brief Create RDATA of a given pair of RR type and class from the +/// \brief Create RDATA of a given pair of RR type and class using the /// master lexer. +/// +/// This is a more generic form of factory from textual RDATA, and is mainly +/// intended to be used internally by the master file parser (\c MasterLoader) +/// of this library. +/// +/// The \c lexer is expected to be at the beginning of textual RDATA of the +/// specified type and class. This function (and its underlying Rdata +/// implementations) extracts necessary tokens from the lexer and constructs +/// the RDATA from them. +/// +/// Due to the intended usage of this version, this function handles error +/// cases quite differently from other versions. It internally catches +/// most of syntax and semantics errors of the input (reported as exceptions), +/// calls the corresponding callback specified by the \c callbacks parameters, +/// and returns a NULL smart pointer. If the caller rather wants to get +/// an exception in these cases, it can use pass a callback that internally +/// throws on error. Some critical exceptions such as \c std::bad_alloc are +/// still propagated to the upper layer as it doesn't make sense to try +/// recovery from such a situation within this function. +/// +/// Whether or not the creation succeeds, this function updates the lexer +/// until it reaches either the end of line or file, starting from the end of +/// the RDATA text (or the point of failure if the parsing fails in the +/// middle of it). The caller can therefore assume it's ready for reading +/// the next data (which is normally a subsequent RR in the zone file) on +/// return, whether or not this function succeeds. +/// +/// \param rrtype An \c RRType object specifying the type/class pair. +/// \param rrclass An \c RRClass object specifying the type/class pair. +/// \param lexer A \c MasterLexer object parsing a master file for the +/// RDATA to be created +/// \param origin If non NULL, specifies the origin of any domain name fields +/// of the RDATA that are non absolute. +/// \param options Master loader options controlling how to deal with errors +/// or non critical issues in the parsed RDATA. +/// \param callbacks Callback to be called when an error or non critical issue +/// is found. +/// \return An \c RdataPtr object pointing to the created +/// \c Rdata object. Will be NULL if parsing fails. RdataPtr createRdata(const RRType& rrtype, const RRClass& rrclass, MasterLexer& lexer, const Name* origin, MasterLoader::Options options, diff --git a/src/lib/dns/rrparamregistry.h b/src/lib/dns/rrparamregistry.h index e156dc95b2..56ae981614 100644 --- a/src/lib/dns/rrparamregistry.h +++ b/src/lib/dns/rrparamregistry.h @@ -119,10 +119,22 @@ public: /// \return An \c RdataPtr object pointing to the created \c Rdata object. virtual RdataPtr create(const rdata::Rdata& source) const = 0; - /// \brief Create RDATA from MasterLexer - virtual RdataPtr create(MasterLexer& lexer, const Name*, - MasterLoader::Options, - MasterLoaderCallbacks&) const; + /// \brief Create RDATA using MasterLexer. + /// + /// This version of the method defines the entry point of factory + /// of a specific RR type and class for \c RRParamRegistry::createRdata() + /// that uses \c MasterLexer. See its description for the expected + /// behavior and meaning of the parameters. + /// + /// \note Right now this is not defined as a pure virtual method and + /// provides the default implementation. This is an intermediate + /// workaround until we implement the underlying constructor for all + /// supported \c Rdata classes; once it's completed the workaround + /// default implementation should be removed and this method should become + /// pure virtual. + virtual RdataPtr create(MasterLexer& lexer, const Name* origin, + MasterLoader::Options options, + MasterLoaderCallbacks& callbacks) const; //@} }; @@ -504,9 +516,20 @@ public: rdata::RdataPtr createRdata(const RRType& rrtype, const RRClass& rrclass, const rdata::Rdata& source); - /// \brief Create RDATA from MasterLexer + /// \brief Create RDATA using MasterLexer + /// + /// This method is expected to be used as the underlying implementation + /// of the same signature of \c rdata::createRdata(). One main + /// difference is that this method is only responsible for constructing + /// the Rdata; it doesn't update the lexer to reach the end of line or + /// file or doesn't care about whether there's an extra (garbage) token + /// after the textual RDATA representation. Another difference is that + /// this method can throw on error and never returns a NULL pointer. + /// + /// For other details and parameters, see the description of + /// \c rdata::createRdata(). rdata::RdataPtr createRdata(const RRType& rrtype, const RRClass& rrclass, - MasterLexer& lexer, const Name* name, + MasterLexer& lexer, const Name* origin, MasterLoader::Options options, MasterLoaderCallbacks& callbacks); //@}