From fee0ab74ff6ae25b22cbbc70578227ea15680758 Mon Sep 17 00:00:00 2001 From: Wojtek Figat Date: Sat, 28 Dec 2024 21:31:21 +0100 Subject: [PATCH] Update old doc comments --- .../Content/Upgraders/AudioClipUpgrader.h | 5 +- .../Content/Upgraders/FontAssetUpgrader.h | 5 +- .../Upgraders/MaterialInstanceUpgrader.h | 5 +- .../Content/Upgraders/ShaderAssetUpgrader.h | 5 +- .../Content/Upgraders/SkeletonMaskUpgrader.h | 5 +- .../Content/Upgraders/TextureAssetUpgrader.h | 5 +- Source/Engine/Core/Types/CommonValue.h | 1 + Source/Engine/Core/Types/TimeSpan.h | 39 +++++++----- Source/Engine/Graphics/RenderView.h | 13 ++-- Source/Engine/Serialization/JsonTools.cpp | 1 + Source/Engine/Serialization/JsonWriter.cpp | 1 + .../Engine/Serialization/MemoryReadStream.h | 44 +++++++------ .../Engine/Serialization/MemoryWriteStream.h | 34 +++++----- Source/Engine/Serialization/Stream.cpp | 2 + Source/Engine/Serialization/WriteStream.h | 62 +++++++------------ Source/Engine/Threading/ConcurrentBuffer.h | 6 +- 16 files changed, 103 insertions(+), 130 deletions(-) diff --git a/Source/Engine/Content/Upgraders/AudioClipUpgrader.h b/Source/Engine/Content/Upgraders/AudioClipUpgrader.h index cf1e2594a..f141c5522 100644 --- a/Source/Engine/Content/Upgraders/AudioClipUpgrader.h +++ b/Source/Engine/Content/Upgraders/AudioClipUpgrader.h @@ -13,12 +13,9 @@ class AudioClipUpgrader : public BinaryAssetUpgrader { public: - /// - /// Initializes a new instance of the class. - /// AudioClipUpgrader() { - static const Upgrader upgraders[] = + const Upgrader upgraders[] = { {}, }; diff --git a/Source/Engine/Content/Upgraders/FontAssetUpgrader.h b/Source/Engine/Content/Upgraders/FontAssetUpgrader.h index 4149816cd..beb1bc8ad 100644 --- a/Source/Engine/Content/Upgraders/FontAssetUpgrader.h +++ b/Source/Engine/Content/Upgraders/FontAssetUpgrader.h @@ -13,12 +13,9 @@ class FontAssetUpgrader : public BinaryAssetUpgrader { public: - /// - /// Initializes a new instance of the class. - /// FontAssetUpgrader() { - static const Upgrader upgraders[] = + const Upgrader upgraders[] = { {}, }; diff --git a/Source/Engine/Content/Upgraders/MaterialInstanceUpgrader.h b/Source/Engine/Content/Upgraders/MaterialInstanceUpgrader.h index e2081e3d3..9209061f6 100644 --- a/Source/Engine/Content/Upgraders/MaterialInstanceUpgrader.h +++ b/Source/Engine/Content/Upgraders/MaterialInstanceUpgrader.h @@ -13,12 +13,9 @@ class MaterialInstanceUpgrader : public BinaryAssetUpgrader { public: - /// - /// Initializes a new instance of the class. - /// MaterialInstanceUpgrader() { - static const Upgrader upgraders[] = + const Upgrader upgraders[] = { {}, }; diff --git a/Source/Engine/Content/Upgraders/ShaderAssetUpgrader.h b/Source/Engine/Content/Upgraders/ShaderAssetUpgrader.h index 97c41dabd..9f815806e 100644 --- a/Source/Engine/Content/Upgraders/ShaderAssetUpgrader.h +++ b/Source/Engine/Content/Upgraders/ShaderAssetUpgrader.h @@ -13,12 +13,9 @@ class ShaderAssetUpgrader : public BinaryAssetUpgrader { public: - /// - /// Initializes a new instance of the class. - /// ShaderAssetUpgrader() { - static const Upgrader upgraders[] = + const Upgrader upgraders[] = { {}, }; diff --git a/Source/Engine/Content/Upgraders/SkeletonMaskUpgrader.h b/Source/Engine/Content/Upgraders/SkeletonMaskUpgrader.h index 0c7944b91..dbaaf13c2 100644 --- a/Source/Engine/Content/Upgraders/SkeletonMaskUpgrader.h +++ b/Source/Engine/Content/Upgraders/SkeletonMaskUpgrader.h @@ -13,12 +13,9 @@ class SkeletonMaskUpgrader : public BinaryAssetUpgrader { public: - /// - /// Initializes a new instance of the class. - /// SkeletonMaskUpgrader() { - static const Upgrader upgraders[] = + const Upgrader upgraders[] = { {}, }; diff --git a/Source/Engine/Content/Upgraders/TextureAssetUpgrader.h b/Source/Engine/Content/Upgraders/TextureAssetUpgrader.h index efe5c6547..afdc9da48 100644 --- a/Source/Engine/Content/Upgraders/TextureAssetUpgrader.h +++ b/Source/Engine/Content/Upgraders/TextureAssetUpgrader.h @@ -13,12 +13,9 @@ class TextureAssetUpgrader : public BinaryAssetUpgrader { public: - /// - /// Initializes a new instance of the class. - /// TextureAssetUpgrader() { - static const Upgrader upgraders[] = + const Upgrader upgraders[] = { {}, }; diff --git a/Source/Engine/Core/Types/CommonValue.h b/Source/Engine/Core/Types/CommonValue.h index 951634cbb..f021b1070 100644 --- a/Source/Engine/Core/Types/CommonValue.h +++ b/Source/Engine/Core/Types/CommonValue.h @@ -16,6 +16,7 @@ /// /// Common values types. +/// [Deprecated on 31.07.2020, expires on 31.07.2022] /// enum class CommonType { diff --git a/Source/Engine/Core/Types/TimeSpan.h b/Source/Engine/Core/Types/TimeSpan.h index 01831c897..d5405acb3 100644 --- a/Source/Engine/Core/Types/TimeSpan.h +++ b/Source/Engine/Core/Types/TimeSpan.h @@ -53,31 +53,37 @@ public: { } - // Init - // @param Days Amount of days - // @param Hours Amount of hours - // @param Minutes Amount of minutes + /// + /// Initializes a new instance of the struct. + /// + /// Amount of days. + /// Amount of hours. + /// Amount of minutes. TimeSpan(int32 days, int32 hours, int32 minutes) { Set(days, hours, minutes, 0, 0); } - // Init - // @param Days Amount of days - // @param Hours Amount of hours - // @param Minutes Amount of minutes - // @param Seconds Amount of seconds + /// + /// Initializes a new instance of the struct. + /// + /// Amount of days. + /// Amount of hours. + /// Amount of minutes. + /// Amount of seconds. TimeSpan(int32 days, int32 hours, int32 minutes, int32 seconds) { Set(days, hours, minutes, seconds, 0); } - // Init - // @param Days Amount of days - // @param Hours Amount of hours - // @param Minutes Amount of minutes - // @param Seconds Amount of seconds - // @param Milliseconds Amount of milliseconds + /// + /// Initializes a new instance of the struct. + /// + /// Amount of days. + /// Amount of hours. + /// Amount of minutes. + /// Amount of seconds. + /// Amount of milliseconds TimeSpan(int32 days, int32 hours, int32 minutes, int32 seconds, int32 milliseconds) { Set(days, hours, minutes, seconds, milliseconds); @@ -87,8 +93,7 @@ public: // Get string String ToString() const; - // Get string - // @param option Custom formatting. Possible values: + // Get string with custom formatting. Possible values: // a: 11:54:22.097 // default: 11:54:22.0972244 String ToString(const char option) const; diff --git a/Source/Engine/Graphics/RenderView.h b/Source/Engine/Graphics/RenderView.h index 0b9f931e7..27bb719d8 100644 --- a/Source/Engine/Graphics/RenderView.h +++ b/Source/Engine/Graphics/RenderView.h @@ -276,17 +276,14 @@ public: /// void UpdateCachedData(); - // Set up view with custom params - // @param viewProjection View * Projection matrix + // Setups view with custom params. void SetUp(const Matrix& viewProjection); - // Set up view with custom params - // @param view View matrix - // @param projection Projection matrix + // Setups view with custom params. void SetUp(const Matrix& view, const Matrix& projection); /// - /// Set up view for cube rendering + /// Setups view for cube rendering. /// /// Near plane /// Far plane @@ -294,13 +291,13 @@ public: void SetUpCube(float nearPlane, float farPlane, const Float3& position); /// - /// Set up view for given face of the cube rendering + /// Setups view for given face of the cube rendering. /// /// Face index(0-5) void SetFace(int32 faceIndex); /// - /// Set up view for cube rendering + /// Setups view for cube rendering. /// /// Near plane /// Far plane diff --git a/Source/Engine/Serialization/JsonTools.cpp b/Source/Engine/Serialization/JsonTools.cpp index 3d6ec8ebf..689ce58c2 100644 --- a/Source/Engine/Serialization/JsonTools.cpp +++ b/Source/Engine/Serialization/JsonTools.cpp @@ -286,6 +286,7 @@ DateTime JsonTools::GetDateTime(const Value& value) CommonValue JsonTools::GetCommonValue(const Value& value) { + // [Deprecated on 31.07.2020, expires on 31.07.2022] CommonValue result; const auto typeMember = value.FindMember("Type"); const auto valueMember = value.FindMember("Value"); diff --git a/Source/Engine/Serialization/JsonWriter.cpp b/Source/Engine/Serialization/JsonWriter.cpp index c8cccc83d..58ee2c126 100644 --- a/Source/Engine/Serialization/JsonWriter.cpp +++ b/Source/Engine/Serialization/JsonWriter.cpp @@ -246,6 +246,7 @@ void JsonWriter::Matrix(const ::Matrix& value) void JsonWriter::CommonValue(const ::CommonValue& value) { + // [Deprecated on 31.07.2020, expires on 31.07.2022] StartObject(); JKEY("Type"); diff --git a/Source/Engine/Serialization/MemoryReadStream.h b/Source/Engine/Serialization/MemoryReadStream.h index 1c5a488d9..3db90f1a6 100644 --- a/Source/Engine/Serialization/MemoryReadStream.h +++ b/Source/Engine/Serialization/MemoryReadStream.h @@ -6,53 +6,63 @@ #include "Engine/Platform/Platform.h" /// -/// Super fast advanced data reading from raw bytes without any overhead at all +/// Direct memory reading stream that uses a single allocation buffer. /// class FLAXENGINE_API MemoryReadStream : public ReadStream { private: - const byte* _buffer; const byte* _position; uint32 _length; public: - /// /// Init (empty, cannot access before Init()) /// - MemoryReadStream(); - /// - /// Init + /// Initializes a new instance of the class. /// - /// Bytes with data to read from it (no memory cloned, using input buffer) + MemoryReadStream(); + + /// + /// Initializes a new instance of the class. + /// + /// Bytes with data to read from it (no memory cloned, using input buffer). /// Amount of bytes MemoryReadStream(const byte* bytes, uint32 length); - + /// - /// Init + /// Initializes a new instance of the class. /// - /// Array with data to read from + /// Array with data to read from. template MemoryReadStream(const Array& data) : MemoryReadStream(data.Get(), data.Count() * sizeof(T)) { } + + /// + /// Initializes a new instance of the class. + /// + /// Span with data to read from. + template + MemoryReadStream(const Span& data) + : MemoryReadStream(data.Get(), data.Count() * sizeof(T)) + { + } public: - /// - /// Init stream to the custom buffer location + /// Init stream to the custom buffer location. /// - /// Bytes with data to read from it (no memory cloned, using input buffer) - /// Amount of bytes + /// Bytes with data to read from it (no memory cloned, using input buffer). + /// Amount of bytes. void Init(const byte* bytes, uint32 length); /// - /// Init stream to the custom buffer location + /// Init stream to the custom buffer location. /// - /// Array with data to read from + /// Array with data to read from. template FORCE_INLINE void Init(const Array& data) { @@ -62,7 +72,6 @@ public: /// /// Gets the current handle to position in buffer. /// - /// The position of the buffer in memory. const byte* GetPositionHandle() const { return _position; @@ -104,7 +113,6 @@ public: } public: - // [ReadStream] void Flush() override; void Close() override; diff --git a/Source/Engine/Serialization/MemoryWriteStream.h b/Source/Engine/Serialization/MemoryWriteStream.h index 568da6585..6b181d3b0 100644 --- a/Source/Engine/Serialization/MemoryWriteStream.h +++ b/Source/Engine/Serialization/MemoryWriteStream.h @@ -5,22 +5,23 @@ #include "WriteStream.h" /// -/// Implementation of of the stream that can be used for fast data writing to the memory. +/// Direct memory writing stream that uses a single allocation buffer. /// class FLAXENGINE_API MemoryWriteStream : public WriteStream { private: - byte* _buffer; byte* _position; uint32 _capacity; public: - - MemoryWriteStream(); - /// - /// Init + /// Initializes a new instance of the class. + /// + MemoryWriteStream(); + + /// + /// Initializes a new instance of the class. /// /// Initial write buffer capacity (in bytes). MemoryWriteStream(uint32 capacity); @@ -31,38 +32,33 @@ public: ~MemoryWriteStream(); public: - /// - /// Gets buffer handle + /// Gets the pointer to the buffer in memory. /// - /// Pointer to the buffer in memory FORCE_INLINE byte* GetHandle() const { return _buffer; } /// - /// Gets current capacity of the memory stream + /// Gets the current capacity of the stream. /// - /// Stream capacity in bytes FORCE_INLINE uint32 GetCapacity() const { return _capacity; } /// - /// Gets current stream length (capacity in bytes) + /// Gets current stream length (capacity in bytes). /// - /// Stream length in bytes FORCE_INLINE uint32 GetLength() const { return _capacity; } /// - /// Gets current position in the stream (in bytes) + /// Gets current position in the stream (in bytes). /// - /// Stream position in bytes FORCE_INLINE uint32 GetPosition() const { return static_cast(_position - _buffer); @@ -97,7 +93,6 @@ public: } public: - /// /// Cleanups the buffers, resets the position and allocated the new memory chunk. /// @@ -105,14 +100,13 @@ public: void Reset(uint32 capacity); /// - /// Saves current buffer contents to the file + /// Saves current buffer contents to the file. /// - /// Filepath - /// True if cannot save data, otherwise false + /// The file path. + /// True if cannot save data, otherwise false. bool SaveToFile(const StringView& path) const; public: - // [WriteStream] void Flush() override; void Close() override; diff --git a/Source/Engine/Serialization/Stream.cpp b/Source/Engine/Serialization/Stream.cpp index 18060b62f..fa9554fbb 100644 --- a/Source/Engine/Serialization/Stream.cpp +++ b/Source/Engine/Serialization/Stream.cpp @@ -107,6 +107,7 @@ void ReadStream::Read(String& data, int16 lock) void ReadStream::Read(CommonValue& data) { + // [Deprecated on 31.07.2020, expires on 31.07.2022] byte type; ReadByte(&type); switch (static_cast(type)) @@ -716,6 +717,7 @@ void WriteStream::Write(const StringAnsiView& data, int8 lock) void WriteStream::Write(const CommonValue& data) { + // [Deprecated on 31.07.2020, expires on 31.07.2022] WriteByte(static_cast(data.Type)); switch (data.Type) { diff --git a/Source/Engine/Serialization/WriteStream.h b/Source/Engine/Serialization/WriteStream.h index 028588ac4..e362e8258 100644 --- a/Source/Engine/Serialization/WriteStream.h +++ b/Source/Engine/Serialization/WriteStream.h @@ -12,129 +12,111 @@ class FLAXENGINE_API WriteStream : public Stream { public: /// - /// Writes bytes to the stream + /// Writes bytes to the stream. /// - /// Data to write - /// Amount of bytes to write + /// Pointer to data to write. + /// Amount of bytes to write. virtual void WriteBytes(const void* data, uint32 bytes) = 0; public: - // Writes byte to the stream - // @param data Data to write + // Writes byte to the stream. FORCE_INLINE void WriteByte(byte data) { WriteBytes(&data, sizeof(byte)); } - // Writes bool to the stream - // @param data Data to write + // Writes bool to the stream. FORCE_INLINE void WriteBool(bool data) { WriteBytes(&data, sizeof(bool)); } - // Writes char to the stream - // @param data Data to write + // Writes char to the stream. FORCE_INLINE void WriteChar(char data) { WriteBytes(&data, sizeof(char)); } - // Writes Char to the stream - // @param data Data to write + // Writes Char to the stream. FORCE_INLINE void WriteChar(Char data) { WriteBytes(&data, sizeof(Char)); } - // Writes uint8 to the stream - // @param data Data to write + // Writes uint8 to the stream. FORCE_INLINE void WriteUint8(uint8 data) { WriteBytes(&data, sizeof(uint8)); } - // Writes int8 to the stream - // @param data Data to write + // Writes int8 to the stream. FORCE_INLINE void WriteInt8(int8 data) { WriteBytes(&data, sizeof(int8)); } - // Writes uint16 to the stream - // @param data Data to write + // Writes uint16 to the stream. FORCE_INLINE void WriteUint16(uint16 data) { WriteBytes(&data, sizeof(uint16)); } - // Writes int16 to the stream - // @param data Data to write + // Writes int16 to the stream. FORCE_INLINE void WriteInt16(int16 data) { WriteBytes(&data, sizeof(int16)); } - // Writes uint32 to the stream - // @param data Data to write + // Writes uint32 to the stream. FORCE_INLINE void WriteUint32(uint32 data) { WriteBytes(&data, sizeof(uint32)); } - // Writes int32 to the stream - // @param data Data to write + // Writes int32 to the stream. FORCE_INLINE void WriteInt32(int32 data) { WriteBytes(&data, sizeof(int32)); } - // Writes int64 to the stream - // @param data Data to write + // Writes int64 to the stream. FORCE_INLINE void WriteInt64(int64 data) { WriteBytes(&data, sizeof(int64)); } - // Writes uint64 to the stream - // @param data Data to write + // Writes uint64 to the stream. FORCE_INLINE void WriteUint64(uint64 data) { WriteBytes(&data, sizeof(uint64)); } - // Writes float to the stream - // @param data Data to write + // Writes float to the stream. FORCE_INLINE void WriteFloat(float data) { WriteBytes(&data, sizeof(float)); } - // Writes double to the stream - // @param data Data to write + // Writes double to the stream. FORCE_INLINE void WriteDouble(double data) { WriteBytes(&data, sizeof(double)); } public: - // Writes text to the stream - // @param data Text to write - // @param length Text length + // Writes text to the stream. void WriteText(const char* text, int32 length) { WriteBytes((const void*)text, sizeof(char) * length); } - // Writes text to the stream - // @param data Text to write - // @param length Text length + // Writes text to the stream. void WriteText(const Char* text, int32 length) { WriteBytes((const void*)text, sizeof(Char) * length); } - // Write UTF BOM character sequence + // Write UTF BOM character sequence. void WriteBOM() { WriteByte(0xEF); @@ -142,8 +124,7 @@ public: WriteByte(0xBF); } - // Writes text to the stream - // @param data Text to write + // Writes text to the stream. void WriteText(const StringView& text); void WriteText(const StringAnsiView& text); @@ -249,7 +230,6 @@ public: // Writes Ansi String to the stream /// [Deprecated on 11.10.2022, expires on 11.10.2024] - // @param data Data to write void WriteStringAnsi(const StringAnsiView& data); // Writes Ansi String to the stream diff --git a/Source/Engine/Threading/ConcurrentBuffer.h b/Source/Engine/Threading/ConcurrentBuffer.h index b109d5629..a5712a046 100644 --- a/Source/Engine/Threading/ConcurrentBuffer.h +++ b/Source/Engine/Threading/ConcurrentBuffer.h @@ -234,8 +234,10 @@ public: return index; } - // Add collection of items to the collection - // @param collection Array with the items to add + /// + /// Adds a collection of items to the collection. + /// + /// The collection of items to add. FORCE_INLINE void Add(ConcurrentBuffer& collection) { Add(collection.Get(), collection.Count());