Include doc comments for stub generation

Author: dktapps

classes/Types.cpp

@@ -36,6 +36,11 @@ ZEND_ARG_OBJ_INFO(0, buffer, pmmp\\encoding\\ByteBufferWriter, 0)
 ZEND_ARG_ARRAY_INFO(0, values, 0)
 ZEND_END_ARG_INFO()
 
+static const char* read_int_array_doc_comment = "/**\n\t * @return int[]\n\t * @phpstan-return list<int>\n\t */";
+static const char* read_float_array_doc_comment = "/**\n\t * @return float[]\n\t * @phpstan-return list<float>\n\t */";
+static const char* write_int_array_doc_comment = "/**\n\t * @param int[] $values\n\t * @phpstan-param list<int> $values\n\t */";
+static const char* write_float_array_doc_comment = "/**\n\t * @param float[] $values\n\t * @phpstan-param list<float> $values\n\t */";
+
 template<typename TValue>
 static inline void zval_long_wrapper(zval* zv, TValue value) {
 	ZVAL_LONG(zv, value);
@@ -246,8 +251,10 @@ ZEND_NAMED_FUNCTION(pmmp_encoding_private_constructor) {
 
 #if PHP_VERSION_ID >= 80400
 #define BC_ZEND_RAW_FENTRY(zend_name, name, arg_info) ZEND_RAW_FENTRY(zend_name, name, arg_info, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC, NULL, NULL)
+#define BC_ZEND_RAW_FENTRY_WITH_DOC_COMMENT(zend_name, name, arg_info, doc_comment) ZEND_RAW_FENTRY(zend_name, name, arg_info, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC, NULL, doc_comment)
 #else
 #define BC_ZEND_RAW_FENTRY(zend_name, name, arg_info) ZEND_RAW_FENTRY(zend_name, name, arg_info, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC)
+#define BC_ZEND_RAW_FENTRY_WITH_DOC_COMMENT(zend_name, name, arg_info, doc_comment) ZEND_RAW_FENTRY(zend_name, name, arg_info, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC)
 #endif
 
 #define TYPE_ENTRIES(zend_name, native_type, read_type, read_result_wrapper, arg_info_read, write_parameter_wrapper, write_type, arg_info_write) \
@@ -275,43 +282,49 @@ ZEND_NAMED_FUNCTION(pmmp_encoding_private_constructor) {
 		arg_info_write \
 	)
 
-#define TYPE_ARRAY_ENTRIES(zend_name, native_type, read_complex_type, read_result_wrapper, write_parameter_wrapper, write_complex_type) \
-	BC_ZEND_RAW_FENTRY( \
+#define TYPE_ARRAY_ENTRIES(zend_name, native_type, read_doc_comment, read_complex_type, read_result_wrapper, write_doc_comment, write_parameter_wrapper, write_complex_type) \
+	BC_ZEND_RAW_FENTRY_WITH_DOC_COMMENT( \
 		"read" zend_name "Array", \
 		(zif_readTypeArray<native_type, read_complex_type, read_result_wrapper<native_type>>), \
-		arginfo_read_array \
+		arginfo_read_array, \
+		read_doc_comment \
 	) \
 	\
-	BC_ZEND_RAW_FENTRY( \
+	BC_ZEND_RAW_FENTRY_WITH_DOC_COMMENT( \
 		"write" zend_name "Array", \
 		(zif_writeTypeArray<native_type, write_parameter_wrapper<native_type>, write_complex_type>), \
-		arginfo_write_array \
+		arginfo_write_array, \
+		write_doc_comment \
 	)
 
-#define FIXED_TYPE_ARRAY_ENTRIES(zend_name, native_type, read_result_wrapper, write_parameter_wrapper, byte_order) \
+#define FIXED_TYPE_ARRAY_ENTRIES(zend_name, native_type, read_doc_comment, read_result_wrapper, write_doc_comment, write_parameter_wrapper, byte_order) \
 	TYPE_ARRAY_ENTRIES( \
 		zend_name, \
 		native_type, \
+		read_doc_comment, \
 		(readFixedSizeTypeArray<native_type, byte_order>), \
 		read_result_wrapper, \
+		write_doc_comment, \
 		write_parameter_wrapper, \
 		(writeFixedSizeTypeArray<native_type, byte_order>) \
 	)
 
-#define COMPLEX_TYPE_ARRAY_ENTRIES(zend_name, native_type, read_element, read_result_wrapper, write_parameter_wrapper, write_element) \
+#define COMPLEX_TYPE_ARRAY_ENTRIES(zend_name, native_type, read_doc_comment, read_element, read_result_wrapper, write_doc_comment, write_parameter_wrapper, write_element) \
 	TYPE_ARRAY_ENTRIES( \
 		zend_name, \
 		native_type, \
+		read_doc_comment, \
 		(readComplexTypeArray<native_type, read_element>), \
 		read_result_wrapper, \
+		write_doc_comment, \
 		write_parameter_wrapper, \
 		(writeComplexTypeArray<native_type, write_element>) \
 	)
 
 #define FIXED_INT_BASE_ENTRIES(zend_name, native_type, byte_order) \
 	FIXED_TYPE_ENTRIES(zend_name, native_type, zend_parse_parameters_long_wrapper, zval_long_wrapper, arginfo_read_integer, arginfo_write_integer, byte_order) \
 	\
-	FIXED_TYPE_ARRAY_ENTRIES(zend_name, native_type, return_long_array, zend_parse_parameters_long_array_wrapper, byte_order)
+	FIXED_TYPE_ARRAY_ENTRIES(zend_name, native_type, read_int_array_doc_comment, return_long_array, write_int_array_doc_comment, zend_parse_parameters_long_array_wrapper, byte_order)
 
 #define FIXED_INT_ENTRIES(zend_name, unsigned_native_type, signed_native_type, byte_order) \
 	FIXED_INT_BASE_ENTRIES("Unsigned" zend_name, unsigned_native_type, byte_order) \
@@ -320,7 +333,7 @@ ZEND_NAMED_FUNCTION(pmmp_encoding_private_constructor) {
 
 #define FLOAT_ENTRIES(zend_name, native_type, byte_order) \
 	FIXED_TYPE_ENTRIES(zend_name, native_type, zend_parse_parameters_double_wrapper, zval_double_wrapper, arginfo_read_float, arginfo_write_float, byte_order) \
-	FIXED_TYPE_ARRAY_ENTRIES(zend_name, native_type, return_double_array, zend_parse_parameters_double_array_wrapper, byte_order)
+	FIXED_TYPE_ARRAY_ENTRIES(zend_name, native_type, read_float_array_doc_comment, return_double_array, write_float_array_doc_comment, zend_parse_parameters_double_array_wrapper, byte_order)
 
 #define COMPLEX_INT_ENTRIES(zend_name, native_type, read_type, write_type) \
 	TYPE_ENTRIES( \
@@ -336,8 +349,10 @@ ZEND_NAMED_FUNCTION(pmmp_encoding_private_constructor) {
 	COMPLEX_TYPE_ARRAY_ENTRIES( \
 		zend_name, \
 		native_type, \
+		read_int_array_doc_comment, \
 		read_type, \
 		return_long_array, \
+		write_int_array_doc_comment, \
 		zend_parse_parameters_long_array_wrapper, \
 		write_type \
 	)

stubs/ByteBufferReader.stub.php

@@ -11,32 +11,32 @@
  * @strict-properties
  */
 final class ByteBufferReader{
-	/**
+	/** @genstubs-expose-comment-block
 	 * Constructs a new ByteBufferReader.
 	 * Offset will be initialized to 0.
 	 */
 	public function __construct(string $data){}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Returns the string (byte array) that the reader is reading.
 	 */
 	public function getData() : string{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Reads $length raw bytes from the buffer at the current offset.
 	 * The internal offset will be updated by this operation.
      *
      * @throws DataDecodeException if there are not enough bytes available
 	 */
 	public function readByteArray(int $length) : string{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Returns the current internal read offset (the position
 	 * from which the next read operation will start).
 	 */
 	public function getOffset() : int{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Sets the internal read offset to the given value.
 	 * The offset must be within the bounds of the buffer
 	 * (0 <= offset <= used length).

stubs/ByteBufferReader_arginfo.h

@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 8f3830b90fe252e654ecab89c16f352e654505f8 */
+ * Stub hash: cf60f8c040fc3c12584760bd1db045b054100c6b */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_pmmp_encoding_ByteBufferReader___construct, 0, 0, 1)
 	ZEND_ARG_TYPE_INFO(0, data, IS_STRING, 0)
@@ -38,11 +38,31 @@ ZEND_METHOD(pmmp_encoding_ByteBufferReader, __unserialize);
 ZEND_METHOD(pmmp_encoding_ByteBufferReader, __debugInfo);
 
 static const zend_function_entry class_pmmp_encoding_ByteBufferReader_methods[] = {
-	ZEND_ME(pmmp_encoding_ByteBufferReader, __construct, arginfo_class_pmmp_encoding_ByteBufferReader___construct, ZEND_ACC_PUBLIC)
-	ZEND_ME(pmmp_encoding_ByteBufferReader, getData, arginfo_class_pmmp_encoding_ByteBufferReader_getData, ZEND_ACC_PUBLIC)
-	ZEND_ME(pmmp_encoding_ByteBufferReader, readByteArray, arginfo_class_pmmp_encoding_ByteBufferReader_readByteArray, ZEND_ACC_PUBLIC)
-	ZEND_ME(pmmp_encoding_ByteBufferReader, getOffset, arginfo_class_pmmp_encoding_ByteBufferReader_getOffset, ZEND_ACC_PUBLIC)
-	ZEND_ME(pmmp_encoding_ByteBufferReader, setOffset, arginfo_class_pmmp_encoding_ByteBufferReader_setOffset, ZEND_ACC_PUBLIC)
+#if (PHP_VERSION_ID >= 80400)
+	ZEND_RAW_FENTRY("__construct", zim_pmmp_encoding_ByteBufferReader___construct, arginfo_class_pmmp_encoding_ByteBufferReader___construct, ZEND_ACC_PUBLIC, NULL, "/**\n	 * Constructs a new ByteBufferReader.\n	 * Offset will be initialized to 0.\n	 */")
+#else
+	ZEND_RAW_FENTRY("__construct", zim_pmmp_encoding_ByteBufferReader___construct, arginfo_class_pmmp_encoding_ByteBufferReader___construct, ZEND_ACC_PUBLIC)
+#endif
+#if (PHP_VERSION_ID >= 80400)
+	ZEND_RAW_FENTRY("getData", zim_pmmp_encoding_ByteBufferReader_getData, arginfo_class_pmmp_encoding_ByteBufferReader_getData, ZEND_ACC_PUBLIC, NULL, "/**\n	 * Returns the string (byte array) that the reader is reading.\n	 */")
+#else
+	ZEND_RAW_FENTRY("getData", zim_pmmp_encoding_ByteBufferReader_getData, arginfo_class_pmmp_encoding_ByteBufferReader_getData, ZEND_ACC_PUBLIC)
+#endif
+#if (PHP_VERSION_ID >= 80400)
+	ZEND_RAW_FENTRY("readByteArray", zim_pmmp_encoding_ByteBufferReader_readByteArray, arginfo_class_pmmp_encoding_ByteBufferReader_readByteArray, ZEND_ACC_PUBLIC, NULL, "/**\n	 * Reads $length raw bytes from the buffer at the current offset.\n	 * The internal offset will be updated by this operation.\n     *\n     * @throws DataDecodeException if there are not enough bytes available\n	 */")
+#else
+	ZEND_RAW_FENTRY("readByteArray", zim_pmmp_encoding_ByteBufferReader_readByteArray, arginfo_class_pmmp_encoding_ByteBufferReader_readByteArray, ZEND_ACC_PUBLIC)
+#endif
+#if (PHP_VERSION_ID >= 80400)
+	ZEND_RAW_FENTRY("getOffset", zim_pmmp_encoding_ByteBufferReader_getOffset, arginfo_class_pmmp_encoding_ByteBufferReader_getOffset, ZEND_ACC_PUBLIC, NULL, "/**\n	 * Returns the current internal read offset (the position\n	 * from which the next read operation will start).\n	 */")
+#else
+	ZEND_RAW_FENTRY("getOffset", zim_pmmp_encoding_ByteBufferReader_getOffset, arginfo_class_pmmp_encoding_ByteBufferReader_getOffset, ZEND_ACC_PUBLIC)
+#endif
+#if (PHP_VERSION_ID >= 80400)
+	ZEND_RAW_FENTRY("setOffset", zim_pmmp_encoding_ByteBufferReader_setOffset, arginfo_class_pmmp_encoding_ByteBufferReader_setOffset, ZEND_ACC_PUBLIC, NULL, "/**\n	 * Sets the internal read offset to the given value.\n	 * The offset must be within the bounds of the buffer\n	 * (0 <= offset <= used length).\n	 *\n	 * @throws \\ValueError if the offset is out of bounds\n	 */")
+#else
+	ZEND_RAW_FENTRY("setOffset", zim_pmmp_encoding_ByteBufferReader_setOffset, arginfo_class_pmmp_encoding_ByteBufferReader_setOffset, ZEND_ACC_PUBLIC)
+#endif
 	ZEND_ME(pmmp_encoding_ByteBufferReader, __serialize, arginfo_class_pmmp_encoding_ByteBufferReader___serialize, ZEND_ACC_PUBLIC)
 	ZEND_ME(pmmp_encoding_ByteBufferReader, __unserialize, arginfo_class_pmmp_encoding_ByteBufferReader___unserialize, ZEND_ACC_PUBLIC)
 	ZEND_ME(pmmp_encoding_ByteBufferReader, __debugInfo, arginfo_class_pmmp_encoding_ByteBufferReader___debugInfo, ZEND_ACC_PUBLIC)

stubs/ByteBufferWriter.stub.php

@@ -11,19 +11,19 @@
  * @strict-properties
  */
 final class ByteBufferWriter{
-	/**
+	/** @genstubs-expose-comment-block
 	 * Constructs a new ByteBufferWriter.
      * The provided string will be written at the start of the buffer as if readByteArray() was called.
 	 */
 	public function __construct(string $prefix = ""){}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Returns a string containing the written bytes.
 	 * Reserved memory is not included.
 	 */
 	public function getData() : string{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Writes the given bytes to the buffer at the current offset.
 	 * The internal offset will be updated by this operation.
 	 *
@@ -34,13 +34,13 @@ public function getData() : string{}
 	 */
 	public function writeByteArray(string $value) : void{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Returns the current internal write offset (the position
 	 * from which the next write operation will start).
 	 */
 	public function getOffset() : int{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Sets the internal write offset to the given value.
 	 * The offset must be within the bounds of the buffer
 	 * (0 <= offset <= reserved length).
@@ -49,34 +49,34 @@ public function getOffset() : int{}
 	 */
 	public function setOffset(int $offset) : void{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Returns the total number of bytes written.
 	 * This will always be less than or equal to the reserved length.
 	 */
 	public function getUsedLength() : int{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Returns the number of bytes reserved by the ByteBuffer.
 	 * This value may be larger than the number of written bytes, as
 	 * some memory may be preallocated to avoid reallocations.
 	 */
 	public function getReservedLength() : int{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Increases buffer capacity to the given value, if the capacity
 	 * is less than this amount. Useful to avoid extra reallocations
 	 * during large write operations when the needed capacity of the
 	 * buffer is known in advance.
 	 */
 	public function reserve(int $length) : void{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Truncates the internal buffer to only the written part,
 	 * discarding any unused reserved memory.
 	 */
 	public function trim() : void{}
 
-	/**
+	/** @genstubs-expose-comment-block
 	 * Clears all data from the buffer. The memory used is retained
 	 * as reserved memory.
 	 */