Fixed -Wdocumentation errors

2026-04-15 00:44:19 +09:00 · 2022-04-27 23:10:49 +02:00
parent bba427e71a
commit cc3e28f2f1
16 changed files with 120 additions and 101 deletions
--- a/channels/client/addin.h
+++ b/channels/client/addin.h
@@ -1,4 +1,4 @@
-/**
+/*
 * FreeRDP: A Remote Desktop Protocol Implementation
 * Channel Addins
 *
@@ -19,8 +19,8 @@

 typedef UINT (*MsgHandler)(LPVOID userdata, wStream* data);

-FREERDP_API void* channel_client_create_handler(rdpContext* ctx, LPVOID userdata, MsgHandler,
-                                                const char* channel_name);
+FREERDP_API void* channel_client_create_handler(rdpContext* ctx, LPVOID userdata,
+                                                MsgHandler handler, const char* channel_name);

 UINT channel_client_post_message(void* MsgsHandle, LPVOID pData, UINT32 dataLength,
                                 UINT32 totalLength, UINT32 dataFlags);
--- a/channels/rdpdr/client/rdpdr_main.c
+++ b/channels/rdpdr/client/rdpdr_main.c
@@ -827,11 +827,6 @@ static BOOL device_already_plugged(rdpdrPlugin* rdpdr, const hotplug_dev* device
 	return !rc;
 }

-/**
- * Function description
- *
- * @return 0 on success, otherwise a Win32 error code
- */
 struct hotplug_delete_arg
 {
 	hotplug_dev* dev_array;
@@ -1228,11 +1223,6 @@ static UINT rdpdr_process_server_clientid_confirm(rdpdrPlugin* rdpdr, wStream* s
 	return CHANNEL_RC_OK;
 }

-/**
- * Function description
- *
- * @return 0 on success, otherwise a Win32 error code
- */
 struct device_announce_arg
 {
 	rdpdrPlugin* rdpdr;
--- a/channels/rdpei/server/rdpei_main.c
+++ b/channels/rdpei/server/rdpei_main.c
@@ -31,7 +31,6 @@
 #include <freerdp/channels/rdpei.h>
 #include <freerdp/server/rdpei.h>

-/** @brief */
 enum RdpEiState
 {
 	STATE_INITIAL,
--- a/channels/rdpgfx/server/rdpgfx_main.c
+++ b/channels/rdpgfx/server/rdpgfx_main.c
@@ -145,7 +145,7 @@ out:
 * to the stream before return, but the pduLength field might be
 * changed in rdpgfx_server_single_packet_send.
 *
- * @param cmdId
+ * @param cmdId The CommandID to write
 * @param dataLen estimated data length without header
 *
 * @return new stream
--- a/channels/video/client/video_main.c
+++ b/channels/video/client/video_main.c
@@ -81,7 +81,6 @@ typedef struct
 static const BYTE MFVideoFormat_H264[] = { 'H',  '2',  '6',  '4',  0x00, 0x00, 0x10, 0x00,
 	                                       0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71 };

-/** @brief */
 typedef struct
 {
 	VideoClientContext* video;
@@ -98,7 +97,6 @@ typedef struct
 	VideoSurface* surface;
 } PresentationContext;

-/** @brief */
 typedef struct
 {
 	UINT64 publishTime;
--- a/client/X11/xf_client.c
+++ b/client/X11/xf_client.c
@@ -1458,7 +1458,8 @@ static BOOL handle_window_events(freerdp* instance)
 *  It will be run from the thread's entry point (thread_func()).
 *  It initiates the connection, and will continue to run until the session ends,
 *  processing events as they are received.
- *  @param instance - pointer to the rdp_freerdp structure that contains the session's settings
+ *
+ *  @param param - pointer to the rdp_freerdp structure that contains the session's settings
 *  @return A code from the enum XF_EXIT_CODE (0 if successful)
 */
 static DWORD WINAPI xf_client_thread(LPVOID param)
--- a/client/common/cmdline.c
+++ b/client/common/cmdline.c
@@ -1407,9 +1407,10 @@ static BOOL ends_with(const char* str, const char* ext)

 /**
 * parses a string value with the format <v1>x<v2>
- * @param input: input string
- * @param v1: pointer to output v1
- * @param v2: pointer to output v2
+ *
+ * @param input input string
+ * @param v1 pointer to output v1
+ * @param v2 pointer to output v2
 * @return if the parsing was successful
 */
 static BOOL parseSizeValue(const char* input, unsigned long* v1, unsigned long* v2)
--- a/include/freerdp/utils/ringbuffer.h
+++ b/include/freerdp/utils/ringbuffer.h
@@ -46,25 +46,32 @@ extern "C"
 {
 #endif

-	/** initialise a ringbuffer
+	/**
+	 * initialise a ringbuffer
+	 *
 	 * @param initialSize the initial capacity of the ringBuffer
 	 * @return if the initialisation was successful
 	 */
 	FREERDP_API BOOL ringbuffer_init(RingBuffer* rb, size_t initialSize);

-	/** destroys internal data used by this ringbuffer
-	 * @param ringbuffer
+	/**
+	 * destroys internal data used by this ringbuffer
+	 *
+	 * @param ringbuffer A pointer to the ringbuffer
 	 */
 	FREERDP_API void ringbuffer_destroy(RingBuffer* ringbuffer);

-	/** computes the space used in this ringbuffer
-	 * @param ringbuffer
+	/**
+	 * computes the space used in this ringbuffer
+	 *
+	 * @param ringbuffer A pointer to the ringbuffer
 	 * @return the number of bytes stored in that ringbuffer
 	 */
 	FREERDP_API size_t ringbuffer_used(const RingBuffer* ringbuffer);

 	/** returns the capacity of the ring buffer
-	 * @param ringbuffer
+	 *
+	 * @param ringbuffer A pointer to the ringbuffer
 	 * @return the capacity of this ring buffer
 	 */
 	FREERDP_API size_t ringbuffer_capacity(const RingBuffer* ringbuffer);
@@ -113,7 +120,7 @@ extern "C"
 	 * This function is used to commit the bytes that were effectively consumed.
 	 *
 	 * @param rb the ring buffer
-	 * @param sz the
+	 * @param sz the number of bytes to read
 	 */
 	FREERDP_API void ringbuffer_commit_read_bytes(RingBuffer* rb, size_t sz);

--- a/libfreerdp/crypto/er.c
+++ b/libfreerdp/crypto/er.c
@@ -86,9 +86,9 @@ int er_get_content_length(int length)

 /**
 * Read er Universal tag.
- * @param s stream
+ * @param s A pointer to the stream to write to
 * @param tag er universally-defined tag
- * @return
+ * @return \b TRUE for success
 */

 BOOL er_read_universal_tag(wStream* s, BYTE tag, BOOL pc)
@@ -319,8 +319,8 @@ int er_skip_octet_string(int length)

 /**
 * Read a er BOOLEAN
- * @param s
- * @param value
+ * @param s A pointer to the stream to read from
+ * @param value A pointer to read the data to
 */

 BOOL er_read_BOOL(wStream* s, BOOL* value)
@@ -340,8 +340,8 @@ BOOL er_read_BOOL(wStream* s, BOOL* value)

 /**
 * Write a er BOOLEAN
- * @param s
- * @param value
+ * @param s A pointer to the stream to write to
+ * @param value The value to write
 */

 void er_write_BOOL(wStream* s, BOOL value)
@@ -393,8 +393,8 @@ BOOL er_read_integer(wStream* s, UINT32* value)

 /**
 * Write a er INTEGER
- * @param s
- * @param value
+ * @param s A pointer to the stream to write to
+ * @param value the value to write
 */

 int er_write_integer(wStream* s, INT32 value)
--- a/libfreerdp/gdi/bitmap.c
+++ b/libfreerdp/gdi/bitmap.c
@@ -42,8 +42,7 @@
 #define TAG FREERDP_TAG("gdi.bitmap")

 /**
- * Get pixel at the given coordinates.\n
- * @msdn{dd144909}
+ * Get pixel at the given coordinates. msdn{dd144909}
 * @param hdc device context
 * @param nXPos pixel x position
 * @param nYPos pixel y position
@@ -65,13 +64,13 @@ BYTE* gdi_GetPointer(HGDI_BITMAP hBmp, UINT32 X, UINT32 Y)
 }

 /**
- * Set pixel at the given coordinates.\n
- * @msdn{dd145078}
- * @param hdc device context
+ * Set pixel at the given coordinates. msdn{dd145078}
+ *
+ * @param hBmp device context
 * @param X pixel x position
 * @param Y pixel y position
 * @param crColor new pixel color
- * @return
+ * @return the color written
 */

 static INLINE UINT32 gdi_SetPixelBmp(HGDI_BITMAP hBmp, UINT32 X, UINT32 Y, UINT32 crColor)
@@ -88,13 +87,12 @@ UINT32 gdi_SetPixel(HGDI_DC hdc, UINT32 X, UINT32 Y, UINT32 crColor)
 }

 /**
- * Create a new bitmap with the given width, height, color format and pixel buffer.\n
- * @msdn{dd183485}
+ * Create a new bitmap with the given width, height, color format and pixel buffer. msdn{dd183485}
+ *
 * @param nWidth width
 * @param nHeight height
- * @param cBitsPerPixel bits per pixel
+ * @param format the color format used
 * @param data pixel buffer
- * @param fkt_free The function used for deallocation of the buffer, NULL for none.
 * @return new bitmap
 */

@@ -103,6 +101,17 @@ HGDI_BITMAP gdi_CreateBitmap(UINT32 nWidth, UINT32 nHeight, UINT32 format, BYTE*
 	return gdi_CreateBitmapEx(nWidth, nHeight, format, 0, data, _aligned_free);
 }

+/**
+ * Create a new bitmap with the given width, height, color format and pixel buffer. msdn{dd183485}
+ *
+ * @param nWidth width
+ * @param nHeight height
+ * @param format the color format used
+ * @param data pixel buffer
+ * @param fkt_free The function used for deallocation of the buffer, NULL for none.
+ * @return new bitmap
+ */
+
 HGDI_BITMAP gdi_CreateBitmapEx(UINT32 nWidth, UINT32 nHeight, UINT32 format, UINT32 stride,
                               BYTE* data, void (*fkt_free)(void*))
 {
--- a/libfreerdp/gdi/gdi.c
+++ b/libfreerdp/gdi/gdi.c
@@ -1106,8 +1106,7 @@ out:

 /**
 * Register GDI callbacks with libfreerdp-core.
- * @param inst current instance
- * @return
+ * @param update current instance
 */

 static void gdi_register_update_callbacks(rdpUpdate* update)
--- a/libfreerdp/gdi/gdi.h
+++ b/libfreerdp/gdi/gdi.h
@@ -51,11 +51,11 @@ static INLINE BYTE* gdi_get_bitmap_pointer(HGDI_DC hdcBmp, INT32 x, INT32 y)
 }

 /**
- * Get current color in brush bitmap according to dest coordinates.\n
- * @msdn{dd183396}
+ * Get current color in brush bitmap according to dest coordinates. msdn{dd183396}
+ *
 * @param x dest x-coordinate
 * @param y dest y-coordinate
- * @return color
+ * @return color pointer
 */
 static INLINE BYTE* gdi_get_brush_pointer(HGDI_DC hdcBrush, UINT32 x, UINT32 y)
 {
--- a/libfreerdp/utils/ringbuffer.c
+++ b/libfreerdp/utils/ringbuffer.c
@@ -150,11 +150,13 @@ static BOOL ringbuffer_realloc(RingBuffer* rb, size_t targetSize)
 }

 /**
+ * Write to a ringbuffer
 *
- * @param rb
- * @param ptr
- * @param sz
- * @return
+ * @param rb A pointer to the ringbuffer
+ * @param ptr A pointer to the data to write
+ * @param sz The number of bytes to write
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */
 BOOL ringbuffer_write(RingBuffer* rb, const BYTE* ptr, size_t sz)
 {
--- a/winpr/libwinpr/comm/comm.c
+++ b/winpr/libwinpr/comm/comm.c
@@ -1141,7 +1141,7 @@ static HANDLE_OPS ops = { CommIsHandled, CommCloseHandle,
 /**
 * http://msdn.microsoft.com/en-us/library/windows/desktop/aa363198%28v=vs.85%29.aspx
 *
- * @param lpDeviceName e.g. COM1, "\\.\COM1", ...
+ * @param lpDeviceName e.g. COM1, ...
 *
 * @param dwDesiredAccess expects GENERIC_READ | GENERIC_WRITE, a
 * warning message is printed otherwise. TODO: better support.
--- a/winpr/libwinpr/sspi/NTLM/ntlm_compute.c
+++ b/winpr/libwinpr/sspi/NTLM/ntlm_compute.c
@@ -45,9 +45,10 @@ static const BYTE NTLM_NULL_BUFFER[16] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0
 	                                       0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };

 /**
- * Populate VERSION structure.
- * VERSION @msdn{cc236654}
- * @param s
+ * Populate VERSION structure msdn{cc236654}
+ * @param versionInfo A pointer to the version struct
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_get_version_info(NTLM_VERSION_INFO* versionInfo)
@@ -68,9 +69,11 @@ BOOL ntlm_get_version_info(NTLM_VERSION_INFO* versionInfo)
 }

 /**
- * Read VERSION structure.
- * VERSION @msdn{cc236654}
- * @param s
+ * Read VERSION structure. msdn{cc236654}
+ * @param s A pointer to a stream to read
+ * @param versionInfo A pointer to the struct to read data to
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_read_version_info(wStream* s, NTLM_VERSION_INFO* versionInfo)
@@ -90,9 +93,11 @@ BOOL ntlm_read_version_info(wStream* s, NTLM_VERSION_INFO* versionInfo)
 }

 /**
- * Write VERSION structure.
- * VERSION @msdn{cc236654}
- * @param s
+ * Write VERSION structure. msdn{cc236654}
+ * @param s A pointer to the stream to write to
+ * @param versionInfo A pointer to the buffer to read the data from
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_write_version_info(wStream* s, const NTLM_VERSION_INFO* versionInfo)
@@ -116,9 +121,8 @@ BOOL ntlm_write_version_info(wStream* s, const NTLM_VERSION_INFO* versionInfo)
 }

 /**
- * Print VERSION structure.
- * VERSION @msdn{cc236654}
- * @param s
+ * Print VERSION structure. msdn{cc236654}
+ * @param versionInfo A pointer to the struct containing the data to print
 */
 #ifdef WITH_DEBUG_NTLM
 void ntlm_print_version_info(const NTLM_VERSION_INFO* versionInfo)
@@ -250,7 +254,8 @@ void ntlm_current_time(BYTE* timestamp)

 /**
 * Generate timestamp for AUTHENTICATE_MESSAGE.
- * @param NTLM context
+ *
+ * @param context A pointer to the NTLM context
 */

 void ntlm_generate_timestamp(NTLM_CONTEXT* context)
@@ -479,9 +484,12 @@ BOOL ntlm_compute_lm_v2_response(NTLM_CONTEXT* context)

 /**
 * Compute NTLMv2 Response.
- * NTLMv2_RESPONSE @msdn{cc236653}
- * NTLMv2 Authentication @msdn{cc236700}
- * @param NTLM context
+ *
+ * NTLMv2_RESPONSE msdn{cc236653}
+ * NTLMv2 Authentication msdn{cc236700}
+ *
+ * @param context A pointer to the NTLM context
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_compute_ntlm_v2_response(NTLM_CONTEXT* context)
@@ -572,7 +580,7 @@ void ntlm_rc4k(BYTE* key, size_t length, BYTE* plaintext, BYTE* ciphertext)

 /**
 * Generate client challenge (8-byte nonce).
- * @param NTLM context
+ * @param context A pointer to the NTLM context
 */

 void ntlm_generate_client_challenge(NTLM_CONTEXT* context)
@@ -586,7 +594,7 @@ void ntlm_generate_client_challenge(NTLM_CONTEXT* context)

 /**
 * Generate server challenge (8-byte nonce).
- * @param NTLM context
+ * @param context A pointer to the NTLM context
 */

 void ntlm_generate_server_challenge(NTLM_CONTEXT* context)
@@ -598,9 +606,8 @@ void ntlm_generate_server_challenge(NTLM_CONTEXT* context)
 }

 /**
- * Generate KeyExchangeKey (the 128-bit SessionBaseKey).
- * @msdn{cc236710}
- * @param NTLM context
+ * Generate KeyExchangeKey (the 128-bit SessionBaseKey). msdn{cc236710}
+ * @param context A pointer to the NTLM context
 */

 void ntlm_generate_key_exchange_key(NTLM_CONTEXT* context)
@@ -614,7 +621,7 @@ void ntlm_generate_key_exchange_key(NTLM_CONTEXT* context)

 /**
 * Generate RandomSessionKey (16-byte nonce).
- * @param NTLM context
+ * @param context A pointer to the NTLM context
 */

 void ntlm_generate_random_session_key(NTLM_CONTEXT* context)
@@ -625,7 +632,7 @@ void ntlm_generate_random_session_key(NTLM_CONTEXT* context)

 /**
 * Generate ExportedSessionKey (the RandomSessionKey, exported)
- * @param NTLM context
+ * @param context A pointer to the NTLM context
 */

 void ntlm_generate_exported_session_key(NTLM_CONTEXT* context)
@@ -638,7 +645,7 @@ void ntlm_generate_exported_session_key(NTLM_CONTEXT* context)

 /**
 * Encrypt RandomSessionKey (RC4-encrypted RandomSessionKey, using KeyExchangeKey as the key).
- * @param NTLM context
+ * @param context A pointer to the NTLM context
 */

 void ntlm_encrypt_random_session_key(NTLM_CONTEXT* context)
@@ -652,7 +659,7 @@ void ntlm_encrypt_random_session_key(NTLM_CONTEXT* context)

 /**
 * Decrypt RandomSessionKey (RC4-encrypted RandomSessionKey, using KeyExchangeKey as the key).
- * @param NTLM context
+ * @param context A pointer to the NTLM context
 */

 void ntlm_decrypt_random_session_key(NTLM_CONTEXT* context)
@@ -683,11 +690,13 @@ void ntlm_decrypt_random_session_key(NTLM_CONTEXT* context)
 }

 /**
- * Generate signing key.
- * @msdn{cc236711}
+ * Generate signing key msdn{cc236711}
+ *
 * @param exported_session_key ExportedSessionKey
 * @param sign_magic Sign magic string
 * @param signing_key Destination signing key
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 static BOOL ntlm_generate_signing_key(BYTE* exported_session_key, const SecBuffer* sign_magic,
@@ -719,9 +728,10 @@ out:
 }

 /**
- * Generate client signing key (ClientSigningKey).
- * @msdn{cc236711}
- * @param NTLM context
+ * Generate client signing key (ClientSigningKey). msdn{cc236711}
+ * @param context A pointer to the NTLM context
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_generate_client_signing_key(NTLM_CONTEXT* context)
@@ -734,9 +744,10 @@ BOOL ntlm_generate_client_signing_key(NTLM_CONTEXT* context)
 }

 /**
- * Generate server signing key (ServerSigningKey).
- * @msdn{cc236711}
- * @param NTLM context
+ * Generate server signing key (ServerSigningKey). msdn{cc236711}
+ * @param context A pointer to the NTLM context
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_generate_server_signing_key(NTLM_CONTEXT* context)
@@ -749,9 +760,10 @@ BOOL ntlm_generate_server_signing_key(NTLM_CONTEXT* context)
 }

 /**
- * Generate client sealing key (ClientSealingKey).
- * @msdn{cc236712}
- * @param NTLM context
+ * Generate client sealing key (ClientSealingKey). msdn{cc236712}
+ * @param context A pointer to the NTLM context
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_generate_client_sealing_key(NTLM_CONTEXT* context)
@@ -764,9 +776,10 @@ BOOL ntlm_generate_client_sealing_key(NTLM_CONTEXT* context)
 }

 /**
- * Generate server sealing key (ServerSealingKey).
- * @msdn{cc236712}
- * @param NTLM context
+ * Generate server sealing key (ServerSealingKey). msdn{cc236712}
+ * @param context A pointer to the NTLM context
+ *
+ * @return \b TRUE for success, \b FALSE for failure
 */

 BOOL ntlm_generate_server_sealing_key(NTLM_CONTEXT* context)
@@ -780,7 +793,7 @@ BOOL ntlm_generate_server_sealing_key(NTLM_CONTEXT* context)

 /**
 * Initialize RC4 stream cipher states for sealing.
- * @param NTLM context
+ * @param context A pointer to the NTLM context
 */

 void ntlm_init_rc4_seal_states(NTLM_CONTEXT* context)
--- a/winpr/libwinpr/sspi/NTLM/ntlm_message.c
+++ b/winpr/libwinpr/sspi/NTLM/ntlm_message.c
@@ -1121,13 +1121,13 @@ fail:
 }

 /**
- * Send NTLMSSP AUTHENTICATE_MESSAGE.\n
- * AUTHENTICATE_MESSAGE @msdn{cc236643}
- * @param NTLM context
- * @param buffer
+ * Send NTLMSSP AUTHENTICATE_MESSAGE. msdn{cc236643}
+ *
+ * @param context Pointer to the NTLM context
+ * @param buffer The buffer to write
 */

-SECURITY_STATUS ntlm_write_AuthenticateMessage(NTLM_CONTEXT* context, PSecBuffer buffer)
+SECURITY_STATUS ntlm_write_AuthenticateMessage(NTLM_CONTEXT* context, const PSecBuffer buffer)
 {
 	wStream sbuffer;
 	wStream* s;