From: jpr <jpr>
Date: Mon, 22 Mar 2004 14:48:34 +0000 (+0000)
Subject: doxygenation
X-Git-Tag: Version0.5.bp~282
X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?a=commitdiff_plain;h=be70f5cdc8ac472bff8ad8a36637457fe49778bd;p=gdcm.git

doxygenation
---

diff --git a/src/gdcmDicomDirElement.cxx b/src/gdcmDicomDirElement.cxx
index 35746ab9..c26b9d32 100644
--- a/src/gdcmDicomDirElement.cxx
+++ b/src/gdcmDicomDirElement.cxx
@@ -71,7 +71,7 @@
 
 /**
  * \ingroup gdcmDicomDirElement
- * \brief   destructor 
+ * \brief   canonical destructor 
  */
  gdcmDicomDirElement::~gdcmDicomDirElement() {
    DicomDirMetaList.clear();
diff --git a/src/gdcmDicomDirElement.h b/src/gdcmDicomDirElement.h
index 2c9a561e..0099c1df 100644
--- a/src/gdcmDicomDirElement.h
+++ b/src/gdcmDicomDirElement.h
@@ -79,10 +79,16 @@ public:
       {return(DicomDirImageList);};
 
 private:
+   /// gdcmElements chained list, related to the MetaElements of DICOMDIR
    ListDicomDirMetaElem    DicomDirMetaList;
+   /// gdcmElements chained list, related to the PatientElements of DICOMDIR
    ListDicomDirPatientElem DicomDirPatientList;
+   /// gdcmElements chained list, related to the StudyElements of DICOMDIR
    ListDicomDirStudyElem   DicomDirStudyList;
+   /// gdcmElements chained list, related to the SerieElements of DICOMDIR
    ListDicomDirSerieElem   DicomDirSerieList;
+   /// gdcmElements chained list, related to the ImageElements of DICOMDIR
+   
    ListDicomDirImageElem   DicomDirImageList;
 };
 
diff --git a/src/gdcmDictSet.h b/src/gdcmDictSet.h
index e970b80b..2c480fff 100644
--- a/src/gdcmDictSet.h
+++ b/src/gdcmDictSet.h
@@ -57,7 +57,7 @@ private:
    DictSetHT Dicts;
    /// Directory path to dictionaries
    std::string DictPath;
-
+   /// H table for the on the fly created gdcmDictEntries  
    std::map<std::string,gdcmDictEntry *> virtualEntry;
 };
 
diff --git a/src/gdcmDirList.cxx b/src/gdcmDirList.cxx
index 5339ebeb..203c0a5f 100644
--- a/src/gdcmDirList.cxx
+++ b/src/gdcmDirList.cxx
@@ -21,12 +21,16 @@
    #include <unistd.h>
 #endif
 
+// ================= WARNING 
+// ================= DOXYGEN DOESN'T WORK FOR THIS FILE ?!?
+// =================
+
 // Constructor / Destructor
 /*
  * \ingroup gdcmDirList
  * \brief Constructor  
- * @param  dirName
- * @param  recursive 
+ * @param  dirName root directory name
+ * @param  recursive whether we want to explore recursively or not 
  */
 gdcmDirList::gdcmDirList(std::string dirName,bool recursive)
 {
diff --git a/src/gdcmException.cxx b/src/gdcmException.cxx
index d1120896..cc95e0cd 100644
--- a/src/gdcmException.cxx
+++ b/src/gdcmException.cxx
@@ -10,8 +10,9 @@
 
 /*
  * \ingroup gdcmException
- * \brief 
- * @param   
+ * \brief constructor
+ * @param f
+ * @param msg  
  */
 gdcmException::gdcmException(const std::string &f, const std::string& msg) throw()
 #ifdef __GNUC__
@@ -28,8 +29,8 @@ catch(...) {
 
 /*
  * \ingroup gdcmException
- * \brief 
- * @param   
+ * \brief fatal
+ * @param from 
  */
  void gdcmException::fatal(const char *from) throw() {
   try {
@@ -51,8 +52,8 @@ catch(...) {
 
 /*
  * \ingroup gdcmException
- * \brief 
- * @param   
+ * \brief getName
+ * @return string
  */
  std::string gdcmException::getName() const throw() {
   try {
@@ -74,7 +75,7 @@ catch(...) {
 	iname = std::string(iname, nb, std::string::npos);
       }
       return name;
-#else             // no class name demangling
+#else           // no class name demangling
       //name = typeid(*this).name();
       return "Exception";
 #endif
@@ -87,7 +88,7 @@ catch(...) {
 
 /*
  * \ingroup gdcmException
- * \brief 
+ * \brief gdcmException::operator
  * @param   
  */
  gdcmException::operator const char *() const throw() {
@@ -97,7 +98,7 @@ catch(...) {
 //-----------------------------------------------------------------------------
 /*
  * \ingroup gdcmException
- * \brief 
+ * \brief gdcmException::operator <<
  * @param   
  */
  std::ostream& operator<<(std::ostream &os, const gdcmException &e) {
diff --git a/src/gdcmFile.cxx b/src/gdcmFile.cxx
index 176b2c8c..f802dcb8 100644
--- a/src/gdcmFile.cxx
+++ b/src/gdcmFile.cxx
@@ -628,7 +628,7 @@ bool gdcmFile::WriteDcmExplVR (std::string fileName) {
  *        (a l'attention des logiciels cliniques 
  *        qui ne prennent en entrée QUE des images ACR ...
  * \warning if a DICOM_V3 header is supplied,
- *         groups < 0x0008 and shadow groups are ignored)
+ *         groups < 0x0008 and shadow groups are ignored
  * \warning NO TEST is performed on processor "Endiannity".
  * @param fileName name of the file to be created
  *                 (any already existing file is overwritten)
diff --git a/src/gdcmHeaderEntry.h b/src/gdcmHeaderEntry.h
index cff9a758..0dab4ad9 100644
--- a/src/gdcmHeaderEntry.h
+++ b/src/gdcmHeaderEntry.h
@@ -220,6 +220,7 @@ private:
    /// the underlying dictionary.	
    bool ImplicitVR;
 			  
+   /// Header Entry value, stores as a std::string (VR will be used, later, to decode)
    std::string  value;
 
    /// unsecure memory area to hold 'non string' values 
@@ -227,7 +228,7 @@ private:
    void *voidArea;
    /// Offset from the begining of file for direct user access		     
    size_t Offset; 
-      
+   /// How many details are to be printed (value : 0,1,2)      
    int printLevel;
 };
 
diff --git a/src/gdcmHeaderHelper.cxx b/src/gdcmHeaderHelper.cxx
index 4317a6f8..9cdab570 100644
--- a/src/gdcmHeaderHelper.cxx
+++ b/src/gdcmHeaderHelper.cxx
@@ -122,7 +122,7 @@ std::string gdcmHeaderHelper::GetPixelType() {
 /**
   * \ingroup gdcmHeaderHelper
   * \brief gets the info from 0028,0030 : Pixel Spacing
-  *             else 1.
+  *             else 1.0
   * @return X dimension of a pixel
   */
 float gdcmHeaderHelper::GetXSpacing() {
@@ -146,7 +146,7 @@ float gdcmHeaderHelper::GetXSpacing() {
 /**
   * \ingroup gdcmHeaderHelper
   * \brief gets the info from 0028,0030 : Pixel Spacing
-  *             else 1.
+  *             else 1.0
   * @return Y dimension of a pixel
   */
 float gdcmHeaderHelper::GetYSpacing() {
@@ -171,7 +171,7 @@ float gdcmHeaderHelper::GetYSpacing() {
   *\ingroup gdcmHeaderHelper
   *\brief gets the info from 0018,0088 : Space Between Slices
   *                else from 0018,0050 : Slice Thickness
-  *                else 1.
+   *                else 1.0
   * @return Z dimension of a voxel-to be
   */
 float gdcmHeaderHelper::GetZSpacing() {
diff --git a/src/gdcmJpeg.cxx b/src/gdcmJpeg.cxx
index 15bdd1a1..1f6e45f4 100644
--- a/src/gdcmJpeg.cxx
+++ b/src/gdcmJpeg.cxx
@@ -147,6 +147,16 @@ METHODDEF(void) my_error_exit (j_common_ptr cinfo) {
  * Sample routine for JPEG decompression.  We assume that the source file name
  * is passed in.  We want to return 1 on success, 0 on error.
  */
+ 
+ /**
+ * \ingroup gdcmFile
+ * \brief   routine for JPEG decompression 
+ * @param fp pointer to an already open file descriptor 
+ *                      8 significant bits per pixel
+ * @param image_buffer to receive uncompressed pixels
+ * @return 1 on success, 0 on error
+ */
+ 
 //GLOBAL(bool)
 bool gdcmFile::gdcm_read_JPEG_file (FILE *fp,void * image_buffer) {
    char *pimage;
diff --git a/src/gdcmJpeg12.cxx b/src/gdcmJpeg12.cxx
index da5be5d8..f67a3fa6 100644
--- a/src/gdcmJpeg12.cxx
+++ b/src/gdcmJpeg12.cxx
@@ -161,6 +161,16 @@ my_error_exit (j_common_ptr cinfo) {
  * Sample routine for JPEG decompression.  We assume that the source file name
  * is passed in.  We want to return 1 on success, 0 on error.
  */
+ 
+ /**
+ * \ingroup gdcmFile
+ * \brief   routine for JPEG decompression 
+ * @param fp pointer to an already open file descriptor 
+ *                      12 significant bits per pixel
+ * @param image_buffer to receive uncompressed pixels
+ * @return 1 on success, 0 on error
+ */
+ 
 bool gdcmFile::gdcm_read_JPEG_file12 (FILE *fp,void * image_buffer) {
    char *pimage;
 
diff --git a/src/gdcmJpeg2000.cxx b/src/gdcmJpeg2000.cxx
index 2d60fe09..1c9c8e49 100644
--- a/src/gdcmJpeg2000.cxx
+++ b/src/gdcmJpeg2000.cxx
@@ -4,6 +4,16 @@
 #include "gdcmFile.h"
 
 //-----------------------------------------------------------------------------
+ /**
+ * \ingroup gdcmFile
+ * \brief   routine for JPEG decompression 
+ * @param fp pointer to an already open file descriptor 
+ *                      JPEG2000 encoded image
+ * @param image_buffer to receive uncompressed pixels
+ * @return 1 on success, 0 on error
+ * @warning : not yet made
+ */
+
 bool gdcmFile::gdcm_read_JPEG2000_file (FILE *fp,void * image_buffer) {
    printf("Sorry JPEG 2000 File not yet taken into account\n");
    return false;
diff --git a/src/gdcmObject.h b/src/gdcmObject.h
index 9d2eca19..7e20d9cc 100644
--- a/src/gdcmObject.h
+++ b/src/gdcmObject.h
@@ -17,10 +17,6 @@ typedef std::list<gdcmObject *> ListContent;
 class GDCM_EXPORT gdcmObject 
 {
 public:
-   gdcmObject(ListTag::iterator begin,ListTag::iterator end,
-              TagHeaderEntryHT *ptagHT, ListTag *plistEntries); 
-   ~gdcmObject(void);
-
    /**
     * \ingroup gdcmParser
     * \brief   Sets the print level for the Dicom Header 
@@ -58,6 +54,11 @@ public:
        { return(endObj);  }
 
 protected:
+ // constructor and destructor are protected to avoid end user to instanciate this class.
+   gdcmObject(ListTag::iterator begin,ListTag::iterator end,
+              TagHeaderEntryHT *ptagHT, ListTag *plistEntries); 
+   ~gdcmObject(void);
+
 
 void FillObject(std::list<gdcmElement> elemList);
 
diff --git a/src/gdcmParser.h b/src/gdcmParser.h
index 4220bfba..8335d9f7 100644
--- a/src/gdcmParser.h
+++ b/src/gdcmParser.h
@@ -35,12 +35,6 @@ typedef std::map<GroupKey, int> GroupHT;
 class GDCM_EXPORT gdcmParser
 {
 public:
-   gdcmParser(bool exception_on_error  = false);
-   gdcmParser(const char *inFilename, 
-              bool  exception_on_error = false, 
-              bool  enable_sequences   = false,
-	      bool  ignore_shadow      = false);
-   virtual ~gdcmParser(void);
 
 // Print
    /**
@@ -126,6 +120,14 @@ public:
    guint32 UnswapLong(guint32);  // needed by gdcmFile
 
 protected:
+// constructor and destructor are protected to forbid end user to instanciate
+// class gdcmParser (only gdcmHeader and gdcmDicomDir are meaningfull)
+   gdcmParser(bool exception_on_error  = false);
+   gdcmParser(const char *inFilename, 
+              bool  exception_on_error = false, 
+              bool  enable_sequences   = false,
+	      bool  ignore_shadow      = false);
+   virtual ~gdcmParser(void);
 // Entry
    int CheckIfEntryExistByNumber(guint16 Group, guint16 Elem ); // int !
    virtual std::string GetEntryByName    (std::string tagName);
@@ -177,8 +179,11 @@ protected:
    */
    FileType filetype;  
 
+/// after opening the file, we read HEADER_LENGTH_TO_READ bytes.
    static const unsigned int HEADER_LENGTH_TO_READ; 
+/// Elements whose value is longer than MAX_SIZE_LOAD_ELEMENT_VALUE are NOT loaded
    static const unsigned int MAX_SIZE_LOAD_ELEMENT_VALUE;
+/// Elements whose value is longer than  MAX_SIZE_PRINT_ELEMENT_VALUE are NOT printed  
    static const unsigned int MAX_SIZE_PRINT_ELEMENT_VALUE;
 
 protected:
diff --git a/src/gdcmRLE.cxx b/src/gdcmRLE.cxx
index 4387ebcf..784b5f59 100644
--- a/src/gdcmRLE.cxx
+++ b/src/gdcmRLE.cxx
@@ -12,8 +12,7 @@
  * \brief     Reads a 'Run Length Encoded' Dicom encapsulated file
  * @param     fp already open File Pointer
  * @param     image_buffer destination Address (in caller's memory space) 
- *            at which the pixel data should be copied
- *   
+ *            at which the pixel data should be copied 
  * @return    Boolean 
  */
 bool gdcmFile::gdcm_read_RLE_file (FILE *fp,void * image_buffer) {
diff --git a/src/gdcmUtil.cxx b/src/gdcmUtil.cxx
index 5b5243de..897899eb 100644
--- a/src/gdcmUtil.cxx
+++ b/src/gdcmUtil.cxx
@@ -11,16 +11,36 @@
 gdcmDebug dbg;
 
 //-----------------------------------------------------------------------------
+/**
+ * \ingroup gdcmDebug
+ * \brief   constructor
+ * @param level debug level
+ */ 
+
 gdcmDebug::gdcmDebug(int level) {
    DebugLevel = level;
 }
 
+/**
+ * \ingroup gdcmDebug
+ * \brief   Verbose 
+ * @param Level level
+ * @param Msg1 first message part
+ * @param Msg2 second message part 
+ */
 void gdcmDebug::Verbose(int Level, const char * Msg1, const char * Msg2) {
    if (Level > DebugLevel)
       return ;
    std::cerr << Msg1 << ' ' << Msg2 << std::endl;
 }
 
+/**
+ * \ingroup gdcmDebug
+ * \brief   Error 
+ * @param Test test
+ * @param Msg1 first message part
+ * @param Msg2 second message part 
+ */
 void gdcmDebug::Error( bool Test, const char * Msg1, const char * Msg2) {
    if (!Test)
       return;
@@ -28,13 +48,28 @@ void gdcmDebug::Error( bool Test, const char * Msg1, const char * Msg2) {
    Exit(1);
 }
 
+/**
+ * \ingroup gdcmDebug
+ * \brief   Error 
+ * @param Msg1 first message part
+ * @param Msg2 second message part
+ * @param Msg3 Third message part  
+ */
 void gdcmDebug::Error(const char* Msg1, const char* Msg2,
                       const char* Msg3) {
    std::cerr << Msg1 << ' ' << Msg2 << ' ' << Msg3 << std::endl;
    Exit(1);
 }
 
-void gdcmDebug::Assert(int Level, bool Test,
+/**
+ * \ingroup gdcmDebug
+ * \brief   Assert 
+ * @param Level level 
+ * @param Test test
+ * @param Msg1 first message part
+ * @param Msg2 second message part
+ */
+ void gdcmDebug::Assert(int Level, bool Test,
                  const char * Msg1, const char * Msg2) {
    if (Level > DebugLevel)
       return ;
@@ -42,6 +77,11 @@ void gdcmDebug::Assert(int Level, bool Test,
       std::cerr << Msg1 << ' ' << Msg2 << std::endl;
 }
 
+/**
+ * \ingroup gdcmDebug
+ * \brief   Exit 
+ * @param a return code 
+ */
 void gdcmDebug::Exit(int a) {
 #ifdef __GNUC__
    std::exit(a);
@@ -52,12 +92,22 @@ void gdcmDebug::Exit(int a) {
 }
 
 //-----------------------------------------------------------------------------
+/// Pointer to a container, holding *all* the Dicom Dictionaries
 gdcmDictSet         *gdcmGlobal::Dicts  = (gdcmDictSet *)0;
+/// Pointer to a H table containing the 'Value Representations'
 gdcmVR              *gdcmGlobal::VR     = (gdcmVR *)0;
+/// Pointer to a H table containing the Transfer Syntax codes and their english description 
 gdcmTS              *gdcmGlobal::TS     = (gdcmTS *)0;
+/// Pointer to a H table containing the Dicom Elements necessary to describe each part of a DICOMDIR 
 gdcmDicomDirElement *gdcmGlobal::ddElem = (gdcmDicomDirElement *)0;
+/// gdcm Glob
 gdcmGlobal gdcmGlob;
 
+
+/**
+ * \ingroup gdcmGlobal
+ * \brief   constructor : populates the
+ */
 gdcmGlobal::gdcmGlobal(void) {
    if (VR || TS || Dicts || ddElem)
       dbg.Verbose(0, "gdcmGlobal::gdcmGlobal : VR or TS or Dicts already allocated");
@@ -67,6 +117,10 @@ gdcmGlobal::gdcmGlobal(void) {
    ddElem = new gdcmDicomDirElement();
 }
 
+/**
+ * \ingroup gdcmGlobal
+ * \brief   canonical destructor 
+ */
 gdcmGlobal::~gdcmGlobal() {
    delete Dicts;
    delete VR;
@@ -125,7 +179,10 @@ void Tokenize (const std::string& str,
 
 
 ///////////////////////////////////////////////////////////////////////////
-// to prevent a flashing screen when non-printable character
+/*
+ * \brief  to prevent a flashing screen when non-printable character
+ * @param 
+ */
 char *_cleanString(char *v) {
    char *d;
    int i, l;
@@ -140,7 +197,10 @@ char *_cleanString(char *v) {
 }
 
 ///////////////////////////////////////////////////////////////////////////
-// to prevent a flashing screen when non-printable character
+/*
+ * \brief   to prevent a flashing screen when non-printable character
+ * @param 
+ */
 std::string _CreateCleanString(std::string s) {
    std::string str=s;
 
@@ -179,6 +239,7 @@ const std::string SEPARATOR = "/";
 ///////////////////////////////////////////////////////////////////////////
 /*
  * \brief   Get the (directory) path from a full path file name
+ * @param 
  */
 std::string GetPath(std::string &fullName)
 {
@@ -194,6 +255,7 @@ std::string GetPath(std::string &fullName)
 ///////////////////////////////////////////////////////////////////////////
 /*
  * \brief   Get the (last) name of a full path file name
+ * @param 
  */
 std::string GetName(std::string &fullName)
 {   
diff --git a/src/gdcmUtil.h b/src/gdcmUtil.h
index af4a6768..4dcbc4fb 100644
--- a/src/gdcmUtil.h
+++ b/src/gdcmUtil.h
@@ -25,19 +25,26 @@
  */
 class gdcmDebug {
 public:
-	gdcmDebug(int level = GDCM_DEBUG);
+   gdcmDebug(int level = GDCM_DEBUG);
 
-	void SetDebug (int i) {DebugLevel = i;}
+  /**
+    * \ingroup gdcmDebug
+    * \brief   sets the debug level 
+    * @param i debug level to be set
+  */ 
+   void SetDebug (int i) 
+      {DebugLevel = i;}
 
    void Verbose(int, const char*, const char* ="");
-	void Error(bool, const char*,  const char* ="");
-	void Error(const char*, const char* ="", const char* ="");
+   void Error(bool, const char*,  const char* ="");
+   void Error(const char*, const char* ="", const char* ="");
 
-	void Assert(int, bool, const char*, const char*);
-	void Exit(int);
+   void Assert(int, bool, const char*, const char*);
+   void Exit(int);
 
 private:
-	int DebugLevel;
+/// warning message level to be displayed
+   int DebugLevel;
 };
 
 //-----------------------------------------------------------------------------
@@ -65,18 +72,18 @@ private:
 //-----------------------------------------------------------------------------
 std::istream & eatwhite(std::istream & is);
 
-void Tokenize (const std::string& str,
-               std::vector<std::string>& tokens,
-               const std::string& delimiters = " ");
+   void Tokenize (const std::string& str,
+                  std::vector<std::string>& tokens,
+                  const std::string& delimiters = " ");
 
-extern gdcmDebug dbg;
+   extern gdcmDebug dbg;
 
-char *_cleanString(char *v);
-std::string _CreateCleanString(std::string s);
+   char *_cleanString(char *v);
+   std::string _CreateCleanString(std::string s);
 
-void NormalizePath (std::string &name);
-std::string GetPath(std::string &fullName);
-std::string GetName(std::string &fullName);
+   void NormalizePath (std::string &name);
+   std::string GetPath(std::string &fullName);
+   std::string GetName(std::string &fullName);
 //-----------------------------------------------------------------------------
 #endif