documentation; refs #27

src/cardos.hxx

@@ -19,15 +19,17 @@
 // use e.g. #define CARDOS_LOG(X) std::clog<<X<<std::endl
 #endif
 
+/** @defgroup gcardos C++ Access to Siemens CardOS V4.4
+    Implements APDUs for accessing Siemens CardOS V4.4 smartcards. */
+//@{
+/// @defgroup cardosexception CardOS Exceptions
+/// @defgroup cardostypes CardOS Types
+/// @defgroup cardoslib CardOS Library
+//@}
+
+/// @ref gcardos @copydoc gcardos
 namespace cardos {
 
-  /// @defgroup gcardos C++ Access to Siemens CardOS V4.4
-  /** Implements APDUs for accessing Siemens CardOS V4.4 smartcards. */
-  //@{
-  /// @defgroup cardosexception CardOS Exceptions
-  /// @defgroup cardostypes CardOS Types
-  /// @defgroup cardoslib CardOS Library
-  
   /// @addtogroup cardosexception CardOS Exceptions
   //@{
   //============================================================================

src/cryptaux.hxx

@@ -14,7 +14,11 @@
 #include <stdexcept>
 #include <algorithm>
 
-/*! @defgroup gcrypto Auxiliary Crypto-Functions */
+/*! @defgroup gcrypto Auxiliary Crypto-Functions
+    
+    Auxiliary often used funcions in cryptographic environment, such
+    as logging, converting binary from and to hexadecimal or creating
+    readable texts from binary data. */
 //@{
 
 #define CRYPTOLOG_QUOTE(X) CRYPTOLOG_QUOTE2(X)
@@ -68,7 +72,7 @@
 #  endif
 #endif
 
-//! @see gcrypto
+//! @ref gcrypto @copydoc gcrypto
 namespace crypto {
   
   static const std::string LETTER_CHARS

src/cryptoki.hxx

@@ -63,7 +63,7 @@ namespace pcsc {
   std::string version();
 }
 
-//! @see gcryptoki
+//! @ref gcryptoki @copydoc gcryptoki
 namespace cryptoki {
 
   //! @addtogroup cryptokitypes

src/openssl.hxx

@@ -60,12 +60,13 @@ namespace pcsc {
   std::string version();
 }
 
-/*! @defgroup gopenssl C++ Wrapper around OpenSSL API */
+/*! @defgroup gopenssl C++ Wrapper around OpenSSL API
+    Support for SSL-connections, engines, keys and certificates. */
 //@{
 //! @defgroup openssllib OpenSSL C++ Library
 //! @defgroup opensslexceptions OpenSSL Exceptions
 
-//! @see gopenssl
+//! @ref gopenssl @copydoc gpcsc
 namespace openssl {
 
   //============================================================================

src/overview.doc

@@ -7,17 +7,71 @@
 
 /*! @mainpage
 
-    There are three namespaces which correspond to the three modules
-    that are implemented here:
-    
-    - @ref gpcsc
-    - @ref gcryptoki
-    - @ref gopenssl
+    The first intention of this 
 
-    All these three libraries deal with hardware token cryptografy and
-    all three libraries are implemented in ugliest C manner. The
-    warpper cares about memory- and resource-management and implements
-    a simple and easy C++ interface, including exceptions for error
-    handling.
-    
+    There are several [Namespaces](namespaces.html) which correspond
+    to the [Modules](modules.html) that are implemented. All libraries
+    libraries deal with hardware token cryptography. Some libraries
+    are just clean C++-wrappers around the original libraries that are
+    implemented in ugliest C manner. The warppers care about memory-
+    and resource-management and implement a simple and easy C++
+    interface, including std::string for binary data and exceptions
+    for error handling.
+
+    For special documentations, such as global overviews and
+    tutorials, please refere to [Pages](pages.html).
+
+    @chapter mainoverview Overview of the Components
+
+    @dot
+    digraph g {
+      compound=true;
+      subgraph clustercard {
+        label="Hardware-Token";
+        token;
+      }
+      subgraph clustersystempcsc {
+        label="System Library PCSC-Lite";
+        pcscd;
+        libpcsclite [shape=component];
+      }
+      subgraph clusteropenssl {
+        label="OpenSSL Library";
+        OpenSSL [shape=component];
+      }
+      subgraph clustermiddleware {
+        label
+        ="Middleware for Hardware Access\ndynamically loaded shared object";
+        pkcs11 [label="libpkcs11.so\nlibcvP11.so\nlibcryptoki.so\n..."]
+               [shape=component];
+      }
+      subgraph clusterlibpcscxx {
+        label="C++ libpcscxx-Library";
+        node [shape=component];
+        pcsc [URL="\ref gpcsc"];
+        cryptoki [URL="\ref gcryptoki"];
+        cardos [URL="\ref gcardos"];
+        suisseid [URL="\ref gsuisseid"];
+        openssl [URL="\ref gopenssl"];
+        crypto [URL="\ref gcrypto"];
+        {rank=same pcsc; cryptoki; openssl; crypto;}
+      }
+      {rank=same OpenSSL; pkcs11;}
+      {pkcs11; OpenSSL; pcsc;} -> libpcsclite [lhead=clustersystempcsc];
+      libpcsclite -> pcscd;
+      pcscd -> token [lhead=clustercard];
+      cryptoki -> pkcs11 [lhead=clustermiddleware];
+      cardos -> pcsc;
+      suisseid -> cardos;
+      suisseid -> cryptoki;
+      openssl -> OpenSSL [lhead=clusteropenssl];
+    }
+    @enddot
+
+    @see gpcsc PCSC-Lite is a middleware to access a smart card using SCard API
+    @see gcryptoki Cryptoki, also known as PKCS#11 is a higher level API
+    @see gopenssl OpenSSL is a high level cryptography library
+    @see gcardos CardOS is an operating system on Siemens smart cards
+    @see gsuisseid SuisseID is a standardized digital identity in Switzerland
+    @see gcrypto Crypto implements some auxiliary crypto funtions
     */

src/pcsc.hxx

@@ -103,7 +103,7 @@ namespace pcsc {
 /*! @defgroup pcsclib PCSC C++ Library */
 /*! @defgroup pcscexceptions PCSC Exceptions */
 
-//! @see gpcsc
+//! @ref gpcsc @copydoc gpcsc
 namespace pcsc {
 
   //============================================================================

src/suisseid.hxx

@@ -14,7 +14,7 @@
 #include <mrw/vector.hxx>
 #include <mrw/shared.hxx>
 
-/*! @defgroup gsuisseid C+ Wrapper to access SuisseID smart cards
+/*! @defgroup gsuisseid C++ library to access SuisseID smart cards
 
     This library allows access to the Swiss digital identity cards
     (SuisseID).
@@ -23,14 +23,29 @@
     suisseid::Scanner to scan for a list of SuisseID cards on the system.
 
     @see http://www.suisseid.ch
-    @see http://postsuisseid.ch */
+    @see http://postsuisseid.ch
+
+*/
 //@{
 /*! @defgroup suisseidlib SuisseID Library */
 /*! @defgroup suisseidtypes SuisseID C++ Types and Auxiliary */
 /*! @defgroup suisseidconsts SuisseID C++ Constants */
 /*! @defgroup suisseidexceptions SuisseID Exceptions */
+/** @example suisse-id-demo.cxx
+
+    Usage of @ref gsuisseid This is a comprehensive example how you
+    can access a SuisseID and access to certificates on that card.
+
+    First implement a status cycle, here for @c std::cin and @c
+    std::cout as user interface in the @c suisse-id-demo.hxx header
+    file:
+
+    @include suisse-id-demo.hxx
+
+    Then instanciate and use this class from your code: */
 //@}
 
+/// @ref gsuisseid @copydoc gsuisseid
 namespace suisseid {