[pclasses-cvs] pclasses2/include/pclasses/System File.h,1.3,1.4 SharedLib.h,1.6,1.7

[stephan b. <sg...@us...>]

Update of /cvsroot/pclasses/pclasses2/include/pclasses/System
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv26827/include/pclasses/System

Modified Files:
	File.h SharedLib.h 
Log Message:
Added API docs. @Christian: Please grep them for @fixme notes!

Index: SharedLib.h
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/include/pclasses/System/SharedLib.h,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- SharedLib.h	25 Dec 2004 07:02:16 -0000	1.6
+++ SharedLib.h	25 Dec 2004 16:04:21 -0000	1.7
@@ -40,7 +40,7 @@
   The example below shows how to retrieve the address of the 
   cos function in the math library:
 \code
-SharedLib shl("libm");
+SharedLib shl("libm.so");
 double (*cosine)(double);
 cosine = shl["cos"];
 (*cosine)(2.0);
@@ -81,9 +81,15 @@
 	  returns a pointer to the symbol.
 	  \return the address of the symbol
 	  NULL if it was not found
+
+	  Throws if symbol is not found or if symbol itself is NULL.
 	*/
 	void* operator[](const char* symbol) throw(RuntimeError);
 
+	/**
+	   Equivalent to the (const char *) version, provided for
+	   convenience. Throws if symbol is empty.
+	*/
 	void* operator[](const std::string& symbol) throw(RuntimeError);
 
 	//! Returns the platform-specific shared lib extension

Index: File.h
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/include/pclasses/System/File.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- File.h	23 Dec 2004 05:56:09 -0000	1.3
+++ File.h	25 Dec 2004 16:04:21 -0000	1.4
@@ -24,54 +24,105 @@
 #include <pclasses/Unicode/String.h>
 #include <pclasses/IO/IODevice.h>
 
-#ifdef PCLASSES_WITH_STL
-#  include <string>
-#endif
+#include <string>
 
 namespace P {
 
 namespace System {
 
+/**
+   File is a cross-platform abstraction for filesystem-based files.
+*/
 class File: public IO::IODevice {
 	public:
 		File() throw();
 
 		File(const File& f) throw(IO::IOError);
 
+		/**
+		   Creates a file with the given name and access modes. Throws on error.
+		 */
 		File(const Unicode::String& name, OpenMode omode, AccessMode amode, 
 			ShareMode smode) throw(IO::IOError);
 
-#ifdef PCLASSES_WITH_STL
+		/**
+		   Creates a file with the given name and access modes. Throws on error.
+		 */
 		File(const std::string& name, OpenMode omode, AccessMode amode, 
 			ShareMode smode) throw(IO::IOError);
-#endif
 
 		~File() throw();
 
+		/**
+		 */
 		void open(const Unicode::String& name, OpenMode omode, AccessMode amode, 
 			ShareMode smode) throw(LogicError, IO::IOError);
 
-#ifdef PCLASSES_WITH_STL
+		/**
+		   Opens this file.
+
+		   @fixme: does this reopen using the new name if open() an already-open()ed
+		   File?
+		 */
 		void open(const std::string& name, OpenMode omode, AccessMode amode, 
 			ShareMode smode) throw(LogicError, IO::IOError);
-#endif
 
+		/**
+		   Frees any resources associated with this object, like filehandles.
+		 */
 		void close() throw(LogicError, IO::IOError);
 
+		/**
+		   Reads up to count bytes and stores them in
+		   buffer. Returns the number of bytes read.
+		 */
 		size_t read(char* buffer, size_t count) throw(IO::IOError);
 
+		/**
+		   Tries to extract up to count bytes from this object
+		   without consuming them. The bytes are stored in
+		   buffer, and the number of bytes read is returned.
+
+		 */
 		size_t peek(char* buffer, size_t count) throw(IO::IOError);
 
+		/**
+		   Writes count bytes from buffer to this object's
+		   internal representation.
+		 */
 		size_t write(const char* buffer, size_t count) throw(IO::IOError);
 
+		/**
+		   Tries to move the current read position to the given offset.
+		   SeekMode determines the relative starting point of offset.
+
+		 */
 		offset_t seek(offset_t offset, SeekMode mode) throw(IO::IOError);
 
+		/**
+		   Returns true if seek() is supported.
+		 */
 		bool isSeekable() const throw();
 
+		/**
+		   @fixme: Same as conventional sync() functions???
+
+		 */
 		void commit() const throw(IO::IOError);
 
+		/**
+		   Returns the size of this File on disk.
+		 */
 		offset_t size() const throw(IO::IOError);
 
+		/**
+		   Copies f.
+
+		   @fixme: what are the semantics for copying the
+		   read/write mode?  Does copying a file this way
+		   really make sense? If f is locked then this ctor
+		   cannot succeed, right?
+		 */
 		File& operator=(const File& f) throw(IO::IOError);
 
 	private: