tests: interesting annotationparser test case

GTK-Doc has trouble parsing multiline parameter
description fields if the first word of a continuation
line is "returns". We're already doing the right thing
but make sure we continue to do so in the future

https://bugzilla.gnome.org/show_bug.cgi?id=708445

1 files changed, 167 insertions, 0 deletions

diff --git a/tests/scanner/annotationparser/gi/syntax_nested_tags.xml b/tests/scanner/annotationparser/gi/syntax_nested_tags.xml
index d1dd54f8..11b5a674 100644
--- a/tests/scanner/annotationparser/gi/syntax_nested_tags.xml
+++ b/tests/scanner/annotationparser/gi/syntax_nested_tags.xml
@@ -60,4 +60,171 @@
  */</output>
 </test>
 
+<test>
+  <input><![CDATA[/**
+ * GSourceFuncs:
+ * @prepare: Called before all the file descriptors are polled. If the
+ *     source can determine that it is ready here (without waiting for the
+ *     results of the poll() call) it should return %TRUE. It can also return
+ *     a @timeout_ value which should be the maximum timeout (in milliseconds)
+ *     which should be passed to the poll() call. The actual timeout used will
+ *     be -1 if all sources returned -1, or it will be the minimum of all the
+ *     @timeout_ values returned which were >= 0.  Since 2.36 this may
+ *     be %NULL, in which case the effect is as if the function always
+ *     returns %FALSE with a timeout of -1.  If @prepare returns a
+ *     timeout and the source also has a 'ready time' set then the
+ *     nearer of the two will be used.
+ * @check: Called after all the file descriptors are polled. The source
+ *     should return %TRUE if it is ready to be dispatched. Note that some
+ *     time may have passed since the previous prepare function was called,
+ *     so the source should be checked again here.  Since 2.36 this may
+ *     be %NULL, in which case the effect is as if the function always
+ *     returns %FALSE.
+ * @dispatch: Called to dispatch the event source, after it has returned
+ *     %TRUE in either its @prepare or its @check function. The @dispatch
+ *     function is passed in a callback function and data. The callback
+ *     function may be %NULL if the source was never connected to a callback
+ *     using g_source_set_callback(). The @dispatch function should call the
+ *     callback function with @user_data and whatever additional parameters
+ *     are needed for this type of event source.
+ * @finalize: Called when the source is finalized.
+ *
+ * The <structname>GSourceFuncs</structname> struct contains a table of
+ * functions used to handle event sources in a generic manner.
+ *
+ * For idle sources, the prepare and check functions always return %TRUE
+ * to indicate that the source is always ready to be processed. The prepare
+ * function also returns a timeout value of 0 to ensure that the poll() call
+ * doesn't block (since that would be time wasted which could have been spent
+ * running the idle function).
+ *
+ * For timeout sources, the prepare and check functions both return %TRUE
+ * if the timeout interval has expired. The prepare function also returns
+ * a timeout value to ensure that the poll() call doesn't block too long
+ * and miss the next timeout.
+ *
+ * For file descriptor sources, the prepare function typically returns %FALSE,
+ * since it must wait until poll() has been called before it knows whether
+ * any events need to be processed. It sets the returned timeout to -1 to
+ * indicate that it doesn't mind how long the poll() call blocks. In the
+ * check function, it tests the results of the poll() call to see if the
+ * required condition has been met, and returns %TRUE if so.
+ */]]></input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>GSourceFuncs</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>prepare</name>
+          <description>Called before all the file descriptors are polled. If the
+    source can determine that it is ready here (without waiting for the
+    results of the poll() call) it should return %TRUE. It can also return
+    a @timeout_ value which should be the maximum timeout (in milliseconds)
+    which should be passed to the poll() call. The actual timeout used will
+    be -1 if all sources returned -1, or it will be the minimum of all the
+    @timeout_ values returned which were >= 0.  Since 2.36 this may
+    be %NULL, in which case the effect is as if the function always
+    returns %FALSE with a timeout of -1.  If @prepare returns a
+    timeout and the source also has a 'ready time' set then the
+    nearer of the two will be used.</description>
+        </parameter>
+        <parameter>
+          <name>check</name>
+          <description>Called after all the file descriptors are polled. The source
+    should return %TRUE if it is ready to be dispatched. Note that some
+    time may have passed since the previous prepare function was called,
+    so the source should be checked again here.  Since 2.36 this may
+    be %NULL, in which case the effect is as if the function always
+    returns %FALSE.</description>
+        </parameter>
+        <parameter>
+          <name>dispatch</name>
+          <description>Called to dispatch the event source, after it has returned
+    %TRUE in either its @prepare or its @check function. The @dispatch
+    function is passed in a callback function and data. The callback
+    function may be %NULL if the source was never connected to a callback
+    using g_source_set_callback(). The @dispatch function should call the
+    callback function with @user_data and whatever additional parameters
+    are needed for this type of event source.</description>
+        </parameter>
+        <parameter>
+          <name>finalize</name>
+          <description>Called when the source is finalized.</description>
+        </parameter>
+      </parameters>
+      <description><![CDATA[The <structname>GSourceFuncs</structname> struct contains a table of
+functions used to handle event sources in a generic manner.
+
+For idle sources, the prepare and check functions always return %TRUE
+to indicate that the source is always ready to be processed. The prepare
+function also returns a timeout value of 0 to ensure that the poll() call
+doesn't block (since that would be time wasted which could have been spent
+running the idle function).
+
+For timeout sources, the prepare and check functions both return %TRUE
+if the timeout interval has expired. The prepare function also returns
+a timeout value to ensure that the poll() call doesn't block too long
+and miss the next timeout.
+
+For file descriptor sources, the prepare function typically returns %FALSE,
+since it must wait until poll() has been called before it knows whether
+any events need to be processed. It sets the returned timeout to -1 to
+indicate that it doesn't mind how long the poll() call blocks. In the
+check function, it tests the results of the poll() call to see if the
+required condition has been met, and returns %TRUE if so.]]></description>
+    </docblock>
+  </parser>
+  <output><![CDATA[/**
+ * GSourceFuncs:
+ * @prepare: Called before all the file descriptors are polled. If the
+ *     source can determine that it is ready here (without waiting for the
+ *     results of the poll() call) it should return %TRUE. It can also return
+ *     a @timeout_ value which should be the maximum timeout (in milliseconds)
+ *     which should be passed to the poll() call. The actual timeout used will
+ *     be -1 if all sources returned -1, or it will be the minimum of all the
+ *     @timeout_ values returned which were >= 0.  Since 2.36 this may
+ *     be %NULL, in which case the effect is as if the function always
+ *     returns %FALSE with a timeout of -1.  If @prepare returns a
+ *     timeout and the source also has a 'ready time' set then the
+ *     nearer of the two will be used.
+ * @check: Called after all the file descriptors are polled. The source
+ *     should return %TRUE if it is ready to be dispatched. Note that some
+ *     time may have passed since the previous prepare function was called,
+ *     so the source should be checked again here.  Since 2.36 this may
+ *     be %NULL, in which case the effect is as if the function always
+ *     returns %FALSE.
+ * @dispatch: Called to dispatch the event source, after it has returned
+ *     %TRUE in either its @prepare or its @check function. The @dispatch
+ *     function is passed in a callback function and data. The callback
+ *     function may be %NULL if the source was never connected to a callback
+ *     using g_source_set_callback(). The @dispatch function should call the
+ *     callback function with @user_data and whatever additional parameters
+ *     are needed for this type of event source.
+ * @finalize: Called when the source is finalized.
+ *
+ * The <structname>GSourceFuncs</structname> struct contains a table of
+ * functions used to handle event sources in a generic manner.
+ *
+ * For idle sources, the prepare and check functions always return %TRUE
+ * to indicate that the source is always ready to be processed. The prepare
+ * function also returns a timeout value of 0 to ensure that the poll() call
+ * doesn't block (since that would be time wasted which could have been spent
+ * running the idle function).
+ *
+ * For timeout sources, the prepare and check functions both return %TRUE
+ * if the timeout interval has expired. The prepare function also returns
+ * a timeout value to ensure that the poll() call doesn't block too long
+ * and miss the next timeout.
+ *
+ * For file descriptor sources, the prepare function typically returns %FALSE,
+ * since it must wait until poll() has been called before it knows whether
+ * any events need to be processed. It sets the returned timeout to -1 to
+ * indicate that it doesn't mind how long the poll() call blocks. In the
+ * check function, it tests the results of the poll() call to see if the
+ * required condition has been met, and returns %TRUE if so.
+ */]]></output>
+</test>
+
 </tests>