From 02d54dd18780728645be36a926322caf1c152485 Mon Sep 17 00:00:00 2001 From: curt Date: Mon, 26 Mar 2001 19:04:52 +0000 Subject: [PATCH] Doxygen. --- SimGear.dsp | 8 +- simgear/math/leastsqs.hxx | 6 +- simgear/xml/easyxml.hxx | 320 ++++++++++++++++++++++++++++++++++++-- 3 files changed, 317 insertions(+), 17 deletions(-) diff --git a/SimGear.dsp b/SimGear.dsp index 8277fb92..d68ea377 100644 --- a/SimGear.dsp +++ b/SimGear.dsp @@ -713,7 +713,7 @@ SOURCE=.\simgear\metar\Stspack3.cpp # PROP Default_Filter "" # Begin Source File -SOURCE=.\simgear\misc\fgpath.cxx +SOURCE=.\simgear\misc\props.cxx !IF "$(CFG)" == "SimGear - Win32 Release" @@ -728,7 +728,7 @@ SOURCE=.\simgear\misc\fgpath.cxx # End Source File # Begin Source File -SOURCE=.\simgear\misc\fgstream.cxx +SOURCE=.\simgear\misc\props_io.cxx !IF "$(CFG)" == "SimGear - Win32 Release" @@ -743,7 +743,7 @@ SOURCE=.\simgear\misc\fgstream.cxx # End Source File # Begin Source File -SOURCE=.\simgear\misc\props.cxx +SOURCE=.\simgear\misc\sg_path.cxx !IF "$(CFG)" == "SimGear - Win32 Release" @@ -758,7 +758,7 @@ SOURCE=.\simgear\misc\props.cxx # End Source File # Begin Source File -SOURCE=.\simgear\misc\props_io.cxx +SOURCE=.\simgear\misc\sgstream.cxx !IF "$(CFG)" == "SimGear - Win32 Release" diff --git a/simgear/math/leastsqs.hxx b/simgear/math/leastsqs.hxx index 7c8e21d3..3e24f77c 100644 --- a/simgear/math/leastsqs.hxx +++ b/simgear/math/leastsqs.hxx @@ -42,12 +42,12 @@ Classical least squares fit: \f] \f[ - b_1 = \frac{n * \sum_0^i (x_i*y_i) - \sum_0^i x_i* \sum_0^i y_i} - {n*\sum_0^i x_i^2 - (\sum_0^i x_i)^2} + b_1 = \frac{n * \sum_0^{i-1} (x_i*y_i) - \sum_0^{i-1} x_i* \sum_0^{i-1} y_i} + {n*\sum_0^{i-1} x_i^2 - (\sum_0^{i-1} x_i)^2} \f] \f[ - b_0 = \frac{\sum_0^i y_i}{n} - b_1 * \frac{\sum_0^i x_i}{n} + b_0 = \frac{\sum_0^{i-1} y_i}{n} - b_1 * \frac{\sum_0^{i-1} x_i}{n} \f] */ void least_squares(double *x, double *y, int n, double *m, double *b); diff --git a/simgear/xml/easyxml.hxx b/simgear/xml/easyxml.hxx index 1697fd35..b042ab39 100644 --- a/simgear/xml/easyxml.hxx +++ b/simgear/xml/easyxml.hxx @@ -1,3 +1,10 @@ +/** + * \file easyxml.hxx + * Declarations for the SimGear XML parser. + * Written by David Megginson, 2000-2001 + * This file is in the Public Domain, and comes with NO WARRANTY of any kind. + */ + #ifndef __EASYXML_HXX #define __EASYXML_HXX @@ -20,40 +27,201 @@ SG_USING_STD(vector); /** * Interface for XML attributes. + * + * This interface is used to provide a list of attributes to the + * application. The interface is a pure abstract class so that + * different implementations can be substituted for the sake of + * efficiency. + * + * @see XMLAttributesDefault */ class XMLAttributes { public: + + /** + * Constructor. + */ XMLAttributes (); + + + /** + * Destructor. + */ virtual ~ XMLAttributes (); + + /** + * Get the number of attributes present. + * + * @return The number of attributes in the list (may be 0). + */ virtual int size () const = 0; + + + /** + * Get the name of an attribute by index. + * + * The index must be less than the size of the list and greater + * than or equal to zero. + * + * @param i The index of the attribute (zero-based). + * @see #size + */ virtual const char * getName (int i) const = 0; + + + /** + * Get the string value of an attribute by index. + * + * The index must be less than the size of the list and greater + * than or equal to zero. + * + * @param i The index of the attribute (zero-based). + * @see #size + */ virtual const char * getValue (int i) const = 0; + + /** + * Look up the index of an attribute by name. + * + * Attribute names must be unique. This method will return + * an index that can be used with the {@link #getValue(const char *)} + * method if the attribute is found. + * + * @param name The name of the attribute. + * @return The index of the attribute with the name specified, + * or -1 if no such attribute is present in the list. + */ virtual int findAttribute (const char * name) const; + + + /** + * Test whether an attribute is present. + * + * @param name The name of the attribute. + * @return true if an attribute with the specified name is present + * in the attribute list, false otherwise. + */ virtual bool hasAttribute (const char * name) const; + + + /** + * Look up the value of an attribute by name. + * + * This method provides a convenient short-cut to invoking + * {@link #findAttribute} and {@link #getValue(const char *)}. + * + * @param name The name of the attribute to look up. + * @return The attribute's value as a string, or 0 if no + * attribute was found with the name specified. + */ virtual const char * getValue (const char * name) const; }; /** * Default mutable attributes implementation. + * + * This class provides a default implementation of the {@link + * XMLAttributes} interface. The implementation is mutable, so + * that it is possible to modify the attribute list when necessary. + * This class is particularly useful for taking a snapshot of + * an attribute list during parsing. + * + * @see XMLAttributes */ class XMLAttributesDefault : public XMLAttributes { public: + + /** + * Default constructor. + */ XMLAttributesDefault (); + + + /** + * Copy constructor. + * + * This constructor is especially useful for taking a static + * snapshot of an attribute list for later use. + * + * @param atts The attribute list to copy. + */ XMLAttributesDefault (const XMLAttributes & atts); + + + /** + * Destructor. + */ virtual ~XMLAttributesDefault (); + + /** + * Count the attributes in the list. + */ virtual int size () const; + + + /** + * Get the name of an attribute by index. + */ virtual const char * getName (int i) const; + + + /** + * Get the value of an attribute by index. + */ virtual const char * getValue (int i) const; + + /** + * Add an attribute to an attribute list. + * + * The name is required to be unique in the list; the value is not. + * + * @param name The name of the attribute to add. + * @param value The value of the attribute to add. + */ virtual void addAttribute (const char * name, const char * value); + + + /** + * Set an attribute name by index. + * + * This method will not extend the list; the attribute must + * already exist. + * + * @param i The index of the attribute (zero-based). + * @param name The new name. + */ virtual void setName (int i, const char * name); + + + /** + * Set an attribute value by index. + * + * This method will not extend the list; the attribute must + * already exist. + * + * @param i The index of the attribute (zero-based). + * @param value The new value. + */ virtual void setValue (int i, const char * value); + + + /** + * Set an attribute value by name. + * + * This method will not extend the list; the attribute must + * already exist. + * + * @param name The name of the attribute that will have the new + * value. + * @param value The new value. + */ virtual void setValue (const char * name, const char * value); private: @@ -64,33 +232,165 @@ private: /** * Visitor class for an XML document. * - * To read an XML document, a module must subclass the visitor to do - * something useful for the different XML events. + * This interface uses the Visitor pattern. The XML parser walks + * through the XML document and invokes the appropriate method in + * this visitor for each piece of markup it finds. By default, + * the methods do nothing; the application must subclass the visitor + * and override the methods for the events it's interested in. + * All applications are required to provide an implementation + * for the {@link #error} callback. */ class XMLVisitor { public: - // start an XML document + + /** + * Callback for the start of an XML document. + * + * The XML parser will invoke this method once, at the beginning of + * the XML document, before any other methods are invoked. The + * application can use this callback to set up data structures, + * open files, etc. + * + * @see #endXML + */ virtual void startXML () {} - // end an XML document + + + /** + * Callback for the end of an XML document. + * + * The XML parser will invoke this method once, at the end of the + * XML document, after all other methods are invoked, and only + * if there have been no parsing errors. The application can use + * this callback to close or write files, finalize data structures, + * and so on, but the application will need to be prepared to + * clean up any resources without this callback in the event of + * an error. + * + * @see #startXML + * @see #error + */ virtual void endXML () {} - // start an element + + + /** + * Callback for the start of an XML element. + * + * The XML parser will invoke this method at the beginning of every + * XML element. Start and end element calls will be balanced + * and properly nested: every element has both a start and end + * callback (even if it was specified with an XML empty element tag), + * there is exactly one root element, and every element must end + * before its parent does. Elements may not overlap. + * Note that the attribute list provided is volatile; it's contents + * are not guaranteed to persist after the end of the callback. + * If the application needs to keep a copy of the attribute list, + * it can make the copy with the {@link XMLAttributesDefault} class. + * + * @param name The name of the element that is starting (not null). + * @param atts The element's attributes (not null). + * @see #endElement + */ virtual void startElement (const char * name, const XMLAttributes &atts) {} - // end an element + + + /** + * Callback for the end of an XML element. + * + * The XML parser will invoke this method at the end of every XML element. + * + * @param name The name of the element that is ending (not null). + * @see #startElement + */ virtual void endElement (const char * name) {} - // character data + + + /** + * Callback for a chunk of character data. + * + * The XML parser will invoke this method once for every chunk of + * character data in the XML document, including whitespace + * separating elements (as required by the XML recommendation). + * Note that character data may be chunked arbitrarily: the + * character data content of an element may be returned in one + * large chunk or several consecutive smaller chunks. + * + * @param s A pointer to the beginning of the character data (not null). + * @param length The number of characters in the chunk (may + * be zero). + */ virtual void data (const char * s, int length) {} - // processing instruction + + + /** + * Callback for an XML processing instruction. + * + * The XML parser will invoke this method once for every processing + * instruction in the XML document. Note that the XML declaration + * and the Text declaration are NOT PROCESSING INSTRUCTIONS and + * will not be reported through this callback. Processing + * instructions are not all that useful, but the XML recommendation + * requires that they be reported. Most applications can safely + * ignore this callback and use the empty default implementation. + * + * @param target The processing instruction target (not null). + * @param data The processing instruction data (not null). + */ virtual void pi (const char * target, const char * data) {} - // non-fatal warning + + + /** + * Callback for an XML parsing warning. + * + * The XML parser will use this callback to report any non-fatal warnings + * during parsing. It is the responsibility of the application to + * deal with the warning in some appropriate way. + * + * @param message The warning message from the parser. + * @param line The number of the line that generated the warning. + * @param column The character position in the line that generated + * the warning. + */ virtual void warning (const char * message, int line, int column) {} - // fatal error + + + /** + * Callback for a fatal XML parsing error. + * + * The XML parser will use this method to report any fatal errors + * during parsing. Once the first error callback is received, + * normal processing will stop, though additional errors may be + * reported. The application should take any appropriate + * error-handling procedures when it receives this callback, and + * should not attempt to use any of the data found in the XML + * document. + * + * @param message The error message from the parser. + * @param line The number of the line that generated the error. + * @param column The character position in the line that generated + * the error. + */ virtual void error (const char * message, int line, int column) = 0; }; /** * Read an XML document. + * + * This function reads an XML document from the input stream provided, + * and invokes the callback methods in the visitor object to pass the + * parsing events back to the application. When this function + * returns, the parser will have reported all of the data in the XML + * document to the application through the visitor callback methods, + * and XML processing will be complete. + * + * @param input The byte input stream containing the XML document. + * @param visitor An object that contains callbacks for XML parsing + * events. + * @return true if the parse succeeded, false if there was a fatal + * error. + * @see XMLVisitor */ extern bool readXML (istream &input, XMLVisitor &visitor); -- 2.39.5