Documentation for Stream

Former-commit-id: 0e77be8d238879c114c5e7b166ae646254fac9eb

include/Nazara/Core/Stream.inl

@@ -7,12 +7,25 @@
 
 namespace Nz
 {
+	/*!
+	* \brief Constructs a Stream object with options
+	*
+	* \param streamOptions Options for the stream
+	* \param openMode Reading/writing mode for the stream
+	*/
+
 	inline Stream::Stream(UInt32 streamOptions, UInt32 openMode) :
 	m_openMode(openMode),
 	m_streamOptions(streamOptions)
 	{
 	}
 
+	/*!
+	* \brief Enables the text mode
+	*
+	* \param textMode Enables the mode or disables
+	*/
+
 	inline void Stream::EnableTextMode(bool textMode)
 	{
 		if (textMode)
@@ -21,6 +34,12 @@ namespace Nz
 			m_streamOptions &= ~StreamOption_Text;
 	}
 
+	/*!
+	* \brief Flushes the stream
+	*
+	* \remark Produces a NazaraAssert if file is not writable
+	*/
+
 	inline void Stream::Flush()
 	{
 		NazaraAssert(IsWritable(), "Stream is not writable");
@@ -28,36 +47,77 @@ namespace Nz
 		FlushStream();
 	}
 
+	/*!
+	* \brief Gets the open mode of the stream
+	* \return Reading/writing mode for the stream
+	*/
+
 	inline UInt32 Stream::GetOpenMode() const
 	{
 		return m_openMode;
 	}
 
+	/*!
+	* \brief Gets the options of the stream
+	* \return Options of the stream
+	*/
+
 	inline UInt32 Stream::GetStreamOptions() const
 	{
 		return m_streamOptions;
 	}
 
+	/*!
+	* \brief Checks whether the stream is readable
+	* \return true if it is the case
+	*/
+
 	inline bool Stream::IsReadable() const
 	{
 		return (m_openMode & OpenMode_ReadOnly) != 0;
 	}
 
+	/*!
+	* \brief Checks whether the stream is sequential
+	* \return true if it is the case
+	*/
+
 	inline bool Stream::IsSequential() const
 	{
 		return (m_streamOptions & StreamOption_Sequential) != 0;
 	}
 
+	/*!
+	* \brief Checks whether the stream has text mode enabled
+	* \return true if it is the case
+	*/
+
 	inline bool Stream::IsTextModeEnabled() const
 	{
 		return (m_streamOptions & StreamOption_Text) != 0;
 	}
 
+	/*!
+	* \brief Checks whether the stream can be written
+	* \return true if it is the case
+	*/
+
 	inline bool Stream::IsWritable() const
 	{
 		return (m_openMode & OpenMode_WriteOnly) != 0;
 	}
 
+	/*!
+	* \brief Reads the stream and puts the result in a buffer
+	* \return Size of the read
+	*
+	* \param buffer Buffer to stock data
+	* \param size Size meant to be read
+	*
+	* \remark Produces a NazaraAssert if stream is not readable
+	* \remark If preallocated space of buffer is less than the size, the behaviour is undefined
+	*/
+
 	inline std::size_t Stream::Read(void* buffer, std::size_t size)
 	{
 		NazaraAssert(IsReadable(), "Stream is not readable");
@@ -65,6 +125,17 @@ namespace Nz
 		return ReadBlock(buffer, size);
 	}
 
+	/*!
+	* \brief Writes in the stream the content of a buffer
+	* \return Size of the writing
+	*
+	* \param buffer Buffer to get data from
+	* \param size Size meant to be written
+	*
+	* \remark Produces a NazaraAssert if stream is not writable
+	* \remark If preallocated space of buffer is less than the size, the behaviour is undefined
+	*/
+
 	inline std::size_t Stream::Write(const void* buffer, std::size_t size)
 	{
 		NazaraAssert(IsWritable(), "Stream is not writable");

src/Nazara/Core/Stream.cpp

@@ -11,22 +11,50 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::Stream
+	* \brief Core class that represents a stream
+	*/
+
+	/*!
+	* \brief Destructs the object
+	*/
+
 	Stream::~Stream() = default;
 
+	/*!
+	* \brief Gets the directory of the stream
+	* \return Empty string (meant to be virtual)
+	*/
+
 	String Stream::GetDirectory() const
 	{
 		return String();
 	}
 
+	/*!
+	* \brief Gets the path of the stream
+	* \return Empty string (meant to be virtual)
+	*/
+
 	String Stream::GetPath() const
 	{
 		return String();
 	}
 
+	/*!
+	* \brief Reads characters in the stream
+	* \return Line containing characters
+	*
+	* \param lineSize Number of characters to read, if lineSize is 0, read as much as possible
+	*
+	* \remark Produces a NazaraWarning if cursor position could not be reset
+	*/
+
 	String Stream::ReadLine(unsigned int lineSize)
 	{
 		String line;
-		if (lineSize == 0) // Taille maximale indéterminée
+		if (lineSize == 0) // Maximal size undefined
 		{
 			const unsigned int bufferSize = 64;
 
@@ -63,7 +91,7 @@ namespace Nz
 			line.Set(lineSize, '\0');
 			std::size_t readSize = Read(&line[0], lineSize);
 			std::size_t pos = line.Find('\n');
-			if (pos <= readSize) // Faux uniquement si le caractère n'est pas présent (npos étant le plus grand entier)
+			if (pos <= readSize) // False only if the character is not available (npos being the biggest integer)
 			{
 				if (m_streamOptions & StreamOption_Text && pos > 0 && line[pos - 1] == '\r')
 					line.Resize(pos);
@@ -80,12 +108,26 @@ namespace Nz
 		return line;
 	}
 
+	/*!
+	* \brief Writes a ByteArray into the stream
+	* \return true if successful
+	*
+	* \param byteArray Bytes to write
+	*/
+
 	bool Stream::Write(const ByteArray& byteArray)
 	{
 		ByteArray::size_type size = byteArray.GetSize();
 		return Write(byteArray.GetConstBuffer(), size) == size;
 	}
 
+	/*!
+	* \brief Writes a String into the stream
+	* \return true if successful
+	*
+	* \param string String to write
+	*/
+
 	bool Stream::Write(const String& string)
 	{
 		String temp(string);