From 28e2077c02f1bb4196730a88aa81aa72de9798e1 Mon Sep 17 00:00:00 2001 From: Scott Cantor Date: Fri, 26 Jan 2007 20:39:31 +0000 Subject: [PATCH] Fixed some doxygen warnings. --- .gitignore | 1 + doc/.gitignore | 1 + doxygen.cfg | 4 ++-- xmltooling/encryption/Decrypter.h | 4 ++-- xmltooling/encryption/Encrypter.h | 2 +- xmltooling/encryption/Encryption.h | 5 +++++ xmltooling/impl/AnyElement.h | 4 +++- xmltooling/io/AbstractXMLObjectMarshaller.h | 23 +++++++++++++++-------- xmltooling/io/AbstractXMLObjectUnmarshaller.h | 4 ++-- xmltooling/security/AbstractPKIXTrustEngine.h | 6 ++++++ xmltooling/security/OpenSSLCryptoX509CRL.h | 16 +++++++++++++++- xmltooling/security/XSECCryptoX509CRL.h | 8 ++++++-- xmltooling/signature/KeyInfo.h | 5 +++++ xmltooling/signature/KeyResolver.h | 1 + xmltooling/signature/Signature.h | 1 + xmltooling/signature/SignatureValidator.h | 8 ++++++++ xmltooling/soap/HTTPSOAPTransport.h | 2 +- xmltooling/soap/SOAP.h | 5 +++++ xmltooling/soap/SOAPClient.h | 6 ++++++ xmltooling/util/ReplayCache.h | 11 +++++++++-- xmltooling/util/Threads.h | 2 +- xmltooling/util/XMLHelper.h | 5 +++++ 22 files changed, 101 insertions(+), 23 deletions(-) create mode 100644 doc/.gitignore diff --git a/.gitignore b/.gitignore index dec8e4c..a71aaf5 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,4 @@ /stamp-h1 /xmltooling.spec /.settings +/doxyfile diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..9ad46ff --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +/api diff --git a/doxygen.cfg b/doxygen.cfg index 30661e8..d762350 100644 --- a/doxygen.cfg +++ b/doxygen.cfg @@ -3,8 +3,8 @@ #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- -PROJECT_NAME = $(PROJECT)-$(VERSION) -PROJECT_NUMBER = +PROJECT_NAME = $(PROJECT) +PROJECT_NUMBER = $(VERSION) OUTPUT_DIRECTORY = $(DOCDIR) CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English diff --git a/xmltooling/encryption/Decrypter.h b/xmltooling/encryption/Decrypter.h index 2ab2b3a..776dc31 100644 --- a/xmltooling/encryption/Decrypter.h +++ b/xmltooling/encryption/Decrypter.h @@ -15,9 +15,9 @@ */ /** - * @file Encrypter.h + * @file xmltooling/encryption/Decrypter.h * - * Methods for encrypting XMLObjects and other data. + * Wrapper API for XML Decryption functionality. */ #if !defined(__xmltooling_decrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC) diff --git a/xmltooling/encryption/Encrypter.h b/xmltooling/encryption/Encrypter.h index c3f3313..ecd6ba3 100644 --- a/xmltooling/encryption/Encrypter.h +++ b/xmltooling/encryption/Encrypter.h @@ -15,7 +15,7 @@ */ /** - * @file Encrypter.h + * @file xmltooling/encryption/Encrypter.h * * Methods for encrypting XMLObjects and other data. */ diff --git a/xmltooling/encryption/Encryption.h b/xmltooling/encryption/Encryption.h index ab1b57c..61f4537 100644 --- a/xmltooling/encryption/Encryption.h +++ b/xmltooling/encryption/Encryption.h @@ -25,6 +25,11 @@ #include +/** + * Macro for declaring encryption builders. + * + * @param cname name of class being built + */ #define DECL_XMLENCOBJECTBUILDER(cname) \ DECL_XMLOBJECTBUILDER(XMLTOOL_API,cname,xmlconstants::XMLENC_NS,xmlconstants::XMLENC_PREFIX) diff --git a/xmltooling/impl/AnyElement.h b/xmltooling/impl/AnyElement.h index 789c6ea..d287154 100644 --- a/xmltooling/impl/AnyElement.h +++ b/xmltooling/impl/AnyElement.h @@ -47,6 +47,7 @@ namespace xmltooling { public AbstractXMLObjectMarshaller, public AbstractXMLObjectUnmarshaller { + /// @cond OFF public: virtual ~AnyElementImpl() {} @@ -62,9 +63,10 @@ namespace xmltooling { IMPL_XMLOBJECT_CHILDREN(UnknownXMLObject,m_children.end()); void marshallAttributes(DOMElement* domElement) const; - void processChildElement(XMLObject* childXMLObject, const DOMElement* root); + void processChildElement(XMLObject* childXMLObject, const DOMElement* childRoot); void processAttribute(const DOMAttr* attribute); }; + /// @endcond /** * Builder for AnyElementImpl objects. diff --git a/xmltooling/io/AbstractXMLObjectMarshaller.h b/xmltooling/io/AbstractXMLObjectMarshaller.h index 5cea6ae..1d77cbe 100644 --- a/xmltooling/io/AbstractXMLObjectMarshaller.h +++ b/xmltooling/io/AbstractXMLObjectMarshaller.h @@ -17,7 +17,7 @@ /** * @file AbstractXMLObjectMarshaller.h * - * A thread-safe abstract marshaller. + * A mix-in to implement object marshalling with DOM reuse. */ #if !defined(__xmltooling_xmlmarshaller_h__) @@ -33,7 +33,7 @@ namespace xmltooling { /** - * A thread-safe abstract marshaller. + * A mix-in to implement object marshalling with DOM reuse. */ class XMLTOOL_API AbstractXMLObjectMarshaller : public virtual AbstractXMLObject { @@ -72,22 +72,29 @@ namespace xmltooling { document->appendChild(element); } +#ifndef XMLTOOLING_NO_XMLSEC /** * Marshalls the XMLObject into the given DOM Element. * The DOM Element must be within a DOM tree rooted in the owning Document. * * @param targetElement the Element into which the XMLObject is marshalled into - * @param ctx optional marshalling context + * @param sigs optional array of signatures to create after marshalling * * @throws MarshallingException thrown if there is a problem marshalling the object * @throws SignatureException thrown if a problem occurs during signature creation */ - void marshallInto( - DOMElement* targetElement -#ifndef XMLTOOLING_NO_XMLSEC - ,const std::vector* sigs + void marshallInto(DOMElement* targetElement, const std::vector* sigs) const; +#else + /** + * Marshalls the XMLObject into the given DOM Element. + * The DOM Element must be within a DOM tree rooted in the owning Document. + * + * @param targetElement the Element into which the XMLObject is marshalled into + * + * @throws MarshallingException thrown if there is a problem marshalling the object + */ + void marshallInto(DOMElement* targetElement) const; #endif - ) const; /** * Creates an xsi:type attribute, corresponding to the given type of the XMLObject, on the DOM element. diff --git a/xmltooling/io/AbstractXMLObjectUnmarshaller.h b/xmltooling/io/AbstractXMLObjectUnmarshaller.h index a69ef1b..9cf9046 100644 --- a/xmltooling/io/AbstractXMLObjectUnmarshaller.h +++ b/xmltooling/io/AbstractXMLObjectUnmarshaller.h @@ -17,7 +17,7 @@ /** * @file AbstractXMLObjectUnmarshaller.h * - * A thread-safe abstract unmarshaller. + * A mix-in to implement object unmarshalling. */ #ifndef __xmltooling_xmlunmarshaller_h__ @@ -33,7 +33,7 @@ namespace xmltooling { /** - * A thread-safe abstract unmarshaller. + * A mix-in to implement object unmarshalling. */ class XMLTOOL_API AbstractXMLObjectUnmarshaller : public virtual AbstractXMLObject { diff --git a/xmltooling/security/AbstractPKIXTrustEngine.h b/xmltooling/security/AbstractPKIXTrustEngine.h index 89f0294..c386fd9 100644 --- a/xmltooling/security/AbstractPKIXTrustEngine.h +++ b/xmltooling/security/AbstractPKIXTrustEngine.h @@ -110,8 +110,14 @@ namespace xmltooling { class XMLTOOL_API PKIXValidationInfoIterator { MAKE_NONCOPYABLE(PKIXValidationInfoIterator); protected: + /** Reference to KeyResolver to use. */ const xmlsignature::KeyResolver& m_keyResolver; + /** + * Constructor + * + * @param keyResolver reference to KeyResolver to use + */ PKIXValidationInfoIterator(const xmlsignature::KeyResolver& keyResolver) : m_keyResolver(keyResolver) {} public: diff --git a/xmltooling/security/OpenSSLCryptoX509CRL.h b/xmltooling/security/OpenSSLCryptoX509CRL.h index ac3c090..6299580 100644 --- a/xmltooling/security/OpenSSLCryptoX509CRL.h +++ b/xmltooling/security/OpenSSLCryptoX509CRL.h @@ -30,6 +30,9 @@ #include namespace xmltooling { + /** + * OpenSSL-based class for handling X.509 CRLs + */ class XMLTOOL_API OpenSSLCryptoX509CRL : public XSECCryptoX509CRL { public: OpenSSLCryptoX509CRL() : mp_X509CRL(NULL), m_DERX509CRL("") {} @@ -44,8 +47,19 @@ namespace xmltooling { return m_DERX509CRL; } + /** + * Constructor + * + * @param x a native CRL object + */ OpenSSLCryptoX509CRL(X509_CRL* x); - X509_CRL* getOpenSSLX509CRL(void) { + + /** + * Returns native CRL object. + * + * @return native CRL object, or NULL + */ + X509_CRL* getOpenSSLX509CRL() { return mp_X509CRL; } diff --git a/xmltooling/security/XSECCryptoX509CRL.h b/xmltooling/security/XSECCryptoX509CRL.h index fd67f20..6c10922 100644 --- a/xmltooling/security/XSECCryptoX509CRL.h +++ b/xmltooling/security/XSECCryptoX509CRL.h @@ -62,13 +62,17 @@ namespace xmltooling { */ virtual XSECCryptoX509CRL* clone() const=0; + /** + * Load a Base64-encoded CRL into the object. + * + * @param buf buffer containing the base64-encoded CRL + * @param len number of bytes of data in the CRL buffer (0 if the string is null terminated) + */ virtual void loadX509CRLBase64Bin(const char* buf, unsigned int len)=0; /** * Load a PEM encoded CRL into the object. * - * Takes a PEM encoded CRL and loads it. - * * @param buf buffer containing the PEM encoded CRL * @param len number of bytes of data in the CRL buffer (0 if the string is null terminated) */ diff --git a/xmltooling/signature/KeyInfo.h b/xmltooling/signature/KeyInfo.h index 720455b..0352f6f 100644 --- a/xmltooling/signature/KeyInfo.h +++ b/xmltooling/signature/KeyInfo.h @@ -28,6 +28,11 @@ #include #include +/** + * Macro for declaring signature builders. + * + * @param cname name of class being built + */ #define DECL_XMLSIGOBJECTBUILDER(cname) \ DECL_XMLOBJECTBUILDER(XMLTOOL_API,cname,xmlconstants::XMLSIG_NS,xmlconstants::XMLSIG_PREFIX) diff --git a/xmltooling/signature/KeyResolver.h b/xmltooling/signature/KeyResolver.h index 6adb039..57fbf14 100644 --- a/xmltooling/signature/KeyResolver.h +++ b/xmltooling/signature/KeyResolver.h @@ -206,6 +206,7 @@ namespace xmlsignature { xmltooling::XSECCryptoX509CRL* resolveCRL(const Signature* sig) const; protected: + /** Stores an explicit key. */ XSECCryptoKey* m_key; /** diff --git a/xmltooling/signature/Signature.h b/xmltooling/signature/Signature.h index f215100..23121b8 100644 --- a/xmltooling/signature/Signature.h +++ b/xmltooling/signature/Signature.h @@ -201,6 +201,7 @@ namespace xmlsignature { #else virtual xmltooling::XMLObject* buildObject() const; #endif + /** Singleton builder. */ static Signature* buildSignature() { const SignatureBuilder* b = dynamic_cast( xmltooling::XMLObjectBuilder::getBuilder( diff --git a/xmltooling/signature/SignatureValidator.h b/xmltooling/signature/SignatureValidator.h index 5ba231d..9724c77 100644 --- a/xmltooling/signature/SignatureValidator.h +++ b/xmltooling/signature/SignatureValidator.h @@ -58,6 +58,11 @@ namespace xmlsignature { virtual void validate(const xmltooling::XMLObject* xmlObject) const; + /** + * Type-safe validator. + * + * @param signature object to validate + */ virtual void validate(const Signature* signature) const; /** @@ -85,7 +90,10 @@ namespace xmlsignature { } protected: + /** Verification key. */ XSECCryptoKey* m_key; + + /** KeyResolver to use against signature. */ KeyResolver* m_resolver; }; diff --git a/xmltooling/soap/HTTPSOAPTransport.h b/xmltooling/soap/HTTPSOAPTransport.h index 0bc5c35..e600fe4 100644 --- a/xmltooling/soap/HTTPSOAPTransport.h +++ b/xmltooling/soap/HTTPSOAPTransport.h @@ -46,7 +46,7 @@ namespace xmltooling { * @param value header value to send * @return true iff the header is successfully set */ - virtual bool setRequestHeader(const char* name, const char* val) const=0; + virtual bool setRequestHeader(const char* name, const char* value) const=0; /** * Returns the values of an HTTP response header. diff --git a/xmltooling/soap/SOAP.h b/xmltooling/soap/SOAP.h index e7aeb22..fdcff4f 100644 --- a/xmltooling/soap/SOAP.h +++ b/xmltooling/soap/SOAP.h @@ -28,6 +28,11 @@ #include #include +/** + * Macro for declaring SOAP builders. + * + * @param cname name of class being built + */ #define DECL_SOAP11OBJECTBUILDER(cname) \ DECL_XMLOBJECTBUILDER(XMLTOOL_API,cname,xmlconstants::SOAP11ENV_NS,xmlconstants::SOAP11ENV_PREFIX) diff --git a/xmltooling/soap/SOAPClient.h b/xmltooling/soap/SOAPClient.h index c1fc633..cc13587 100644 --- a/xmltooling/soap/SOAPClient.h +++ b/xmltooling/soap/SOAPClient.h @@ -41,7 +41,13 @@ namespace soap11 { { MAKE_NONCOPYABLE(SOAPClient); public: + /** + * Constructor + * + * @param validate true iff schema validation should be used + */ SOAPClient(bool validate=false) : m_validate(validate), m_transport(NULL) {} + virtual ~SOAPClient(); /** diff --git a/xmltooling/util/ReplayCache.h b/xmltooling/util/ReplayCache.h index 590b519..eeb9f21 100644 --- a/xmltooling/util/ReplayCache.h +++ b/xmltooling/util/ReplayCache.h @@ -56,8 +56,15 @@ namespace xmltooling { */ virtual bool check(const char* context, const char* s, time_t expires); - bool check(const char* context, const XMLCh* str, time_t expires) { - auto_ptr_char temp(str); + /** + * Returns true iff the check value is not found in the cache, and stores it. + * + * @param context a context label to subdivide the cache + * @param s value to check + * @param expires time for disposal of value from cache + */ + bool check(const char* context, const XMLCh* s, time_t expires) { + auto_ptr_char temp(s); return check(context, temp.get(), expires); } diff --git a/xmltooling/util/Threads.h b/xmltooling/util/Threads.h index 50d031f..bae751d 100644 --- a/xmltooling/util/Threads.h +++ b/xmltooling/util/Threads.h @@ -84,7 +84,7 @@ namespace xmltooling * * @param seconds time to sleep */ - static void sleep(int secounds); + static void sleep(int seconds); #ifndef WIN32 /** * Masks all signals from a thread. diff --git a/xmltooling/util/XMLHelper.h b/xmltooling/util/XMLHelper.h index 41b2e88..33bc077 100644 --- a/xmltooling/util/XMLHelper.h +++ b/xmltooling/util/XMLHelper.h @@ -40,6 +40,11 @@ namespace xmltooling { MAKE_NONCOPYABLE(XercesJanitor); T* m_held; public: + /** + * Constructor + * + * @param resource object to release when leaving scope + */ XercesJanitor(T* resource) : m_held(resource) {} ~XercesJanitor() { -- 2.1.4