Better comment for new shared library feature

mrw/stacktrace.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.8  2004/10/11 16:49:32  marc
+    Better comment for new shared library feature
+
     Revision 1.7  2004/10/11 15:58:51  marc
     First version with working support for shared libraries!
 
@@ -187,30 +190,41 @@ namespace mrw {
       static CodePos translate(void* addr)
         throw(std::bad_exception);
     
-      /** @brief read the symbol table from the executable file
+      /** @brief read the symbol table from the executable file or a
+          shared library
+
+          On Solaris and Linux, the name of the executable is
+          automatically detected through the @c /dev/proc file
+          system. Only on Linux the shared libraries are detected
+          through a call to @c ldd. So you may leave the parameter
+          empty on these systems.
 
-          @param fname The file name of the executable. On Linux
+          @param fname The file name of the executable or a shared
-          and Solaris, this can be evaluated automatically, so the
+          library. On Linux and Solaris, this can be evaluated
-          parameter is optional.
+          automatically, so the parameter is optional.
 
           @param offs Offset of the address space. It is 0 for
-          executables, but must be given for shared libraries.
+          executables, but must be given for shared libraries. Use @c
+          ldd on the executable to find out the offset.
 
           @return @c true in case of success. If @c false is returned,
           the symbol table was not read and the evaluation cannot be
           done. Printing then only prints the raw addresses, without
           file, line nmber information and method names.
 
-          @note This method must be executed once before a stack trace
+          @note createSymtable must be executed at least once before a
-          is printed the very first time. For storing a stack trace
+          stack trace is printed the very first time. For storing a
-          (that means for the creation of a mrw::StackTrace object) a
+          stack trace (that means for the creation of a
-          call to this method is not yet needed.
+          mrw::StackTrace object) a call to this method is not yet
+          needed.
 
-          @note Call only one of both createSymtable methods!
+          @note In general, call only one of both createSymtable
+          methods! But instead of callin the other method once, you
+          may also call this one several times.
 
-          @note If this method is called more than once, the symbols
+          @note If this method is called more than once for the same
-          are created only the first time, so you don't loose too much
+          file, the symbols are created only the first time, so you
-          time.
+          don't loose too much time.
        */
       static bool createSymtable(const std::string& fname="", void* offs=0)
         throw(std::bad_exception);
@@ -234,11 +248,10 @@ namespace mrw {
           (that means for the creation of a mrw::StackTrace object) a
           call to this method is not yet needed.
 
-          @note Call only one of both createSymtable methods!
+          @note In general, call only one of both createSymtable methods!
 
-          @note If this method is called more than once, the symbols
+          @note This method calls the other one for all files in
-          are created only the first time, so you don't loose too much
+          parameter @c files.
-          time.
       */
       static bool createSymtable(const BinFiles& files) throw(std::bad_exception);