Update documentation

docs/gstreamer-base/docs.md

@@ -546,6 +546,187 @@ a `glib::List` of
  bytes are not available
 <!-- impl Adapter::fn unmap -->
 Releases the memory obtained with the last `Adapter::map`.
+<!-- struct Aggregator -->
+Manages a set of pads with the purpose of aggregating their buffers.
+Control is given to the subclass when all pads have data.
+
+ * Base class for mixers and muxers. Subclasses should at least implement
+ the `AggregatorClass.aggregate`() virtual method.
+
+ * Installs a `GstPadChainFunction`, a `GstPadEventFullFunction` and a
+ `GstPadQueryFunction` to queue all serialized data packets per sink pad.
+ Subclasses should not overwrite those, but instead implement
+ `AggregatorClass.sink_event`() and `AggregatorClass.sink_query`() as
+ needed.
+
+ * When data is queued on all pads, the aggregate vmethod is called.
+
+ * One can peek at the data on any given GstAggregatorPad with the
+ gst_aggregator_pad_peek_buffer () method, and remove it from the pad
+ with the gst_aggregator_pad_pop_buffer () method. When a buffer
+ has been taken with pop_buffer (), a new buffer can be queued
+ on that pad.
+
+ * If the subclass wishes to push a buffer downstream in its aggregate
+ implementation, it should do so through the
+ gst_aggregator_finish_buffer () method. This method will take care
+ of sending and ordering mandatory events such as stream start, caps
+ and segment.
+
+ * Same goes for EOS events, which should not be pushed directly by the
+ subclass, it should instead return GST_FLOW_EOS in its aggregate
+ implementation.
+
+ * Note that the aggregator logic regarding gap event handling is to turn
+ these into gap buffers with matching PTS and duration. It will also
+ flag these buffers with GST_BUFFER_FLAG_GAP and GST_BUFFER_FLAG_DROPPABLE
+ to ease their identification and subsequent processing.
+
+ * Subclasses must use (a subclass of) `AggregatorPad` for both their
+ sink and source pads.
+ See `gst::ElementClass::add_static_pad_template_with_gtype`.
+
+This class used to live in gst-plugins-bad and was moved to core.
+
+Feature: `v1_14`
+
+# Implements
+
+[`AggregatorExt`](trait.AggregatorExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
+<!-- trait AggregatorExt -->
+Trait containing all `Aggregator` methods.
+
+Feature: `v1_14`
+
+# Implementors
+
+[`Aggregator`](struct.Aggregator.html)
+<!-- trait AggregatorExt::fn finish_buffer -->
+This method will push the provided output buffer downstream. If needed,
+mandatory events such as stream-start, caps, and segment events will be
+sent before pushing the buffer.
+
+Feature: `v1_14`
+
+## `buffer`
+the `gst::Buffer` to push.
+<!-- trait AggregatorExt::fn get_allocator -->
+Lets `Aggregator` sub-classes get the memory `allocator`
+acquired by the base class and its `params`.
+
+Unref the `allocator` after use it.
+
+Feature: `v1_14`
+
+## `allocator`
+the `gst::Allocator`
+used
+## `params`
+the
+`gst::AllocationParams` of `allocator`
+<!-- trait AggregatorExt::fn get_buffer_pool -->
+
+Feature: `v1_14`
+
+
+# Returns
+
+the instance of the `gst::BufferPool` used
+by `trans`; free it after use it
+<!-- trait AggregatorExt::fn get_latency -->
+Retrieves the latency values reported by `self` in response to the latency
+query, or `GST_CLOCK_TIME_NONE` if there is not live source connected and the element
+will not wait for the clock.
+
+Typically only called by subclasses.
+
+Feature: `v1_14`
+
+
+# Returns
+
+The latency or `GST_CLOCK_TIME_NONE` if the element does not sync
+<!-- trait AggregatorExt::fn set_latency -->
+Lets `Aggregator` sub-classes tell the baseclass what their internal
+latency is. Will also post a LATENCY message on the bus so the pipeline
+can reconfigure its global latency.
+
+Feature: `v1_14`
+
+## `min_latency`
+minimum latency
+## `max_latency`
+maximum latency
+<!-- trait AggregatorExt::fn set_src_caps -->
+Sets the caps to be used on the src pad.
+
+Feature: `v1_14`
+
+## `caps`
+The `gst::Caps` to set on the src pad.
+<!-- struct AggregatorPad -->
+Pads managed by a `GstAggregor` subclass.
+
+This class used to live in gst-plugins-bad and was moved to core.
+
+Feature: `v1_14`
+
+# Implements
+
+[`AggregatorPadExt`](trait.AggregatorPadExt.html), [`gst::PadExt`](../gst/trait.PadExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
+<!-- trait AggregatorPadExt -->
+Trait containing all `AggregatorPad` methods.
+
+Feature: `v1_14`
+
+# Implementors
+
+[`AggregatorPad`](struct.AggregatorPad.html)
+<!-- trait AggregatorPadExt::fn drop_buffer -->
+Drop the buffer currently queued in `self`.
+
+Feature: `v1_14`
+
+
+# Returns
+
+TRUE if there was a buffer queued in `self`, or FALSE if not.
+<!-- trait AggregatorPadExt::fn has_buffer -->
+
+Feature: `v1_14_1`
+
+
+# Returns
+
+`true` if the pad has a buffer available as the next thing.
+<!-- trait AggregatorPadExt::fn is_eos -->
+
+Feature: `v1_14`
+
+
+# Returns
+
+`true` if the pad is EOS, otherwise `false`.
+<!-- trait AggregatorPadExt::fn peek_buffer -->
+
+Feature: `v1_14`
+
+
+# Returns
+
+A reference to the buffer in `self` or
+NULL if no buffer was queued. You should unref the buffer after
+usage.
+<!-- trait AggregatorPadExt::fn pop_buffer -->
+Steal the ref to the buffer currently queued in `self`.
+
+Feature: `v1_14`
+
+
+# Returns
+
+The buffer in `self` or NULL if no buffer was
+ queued. You should unref the buffer after usage.
 <!-- struct BaseSink -->
 `BaseSink` is the base class for sink elements in GStreamer, such as
 xvimagesink or filesink. It is a layer on top of `gst::Element` that provides a

docs/gstreamer-check/docs.md

@@ -0,0 +1,308 @@
+<!-- file * -->
+<!-- struct TestClock -->
+GstTestClock is an implementation of `gst::Clock` which has different
+behaviour compared to `gst::SystemClock`. Time for `gst::SystemClock` advances
+according to the system time, while time for `TestClock` changes only
+when `TestClock::set_time` or `TestClock::advance_time` are
+called. `TestClock` provides unit tests with the possibility to
+precisely advance the time in a deterministic manner, independent of the
+system time or any other external factors.
+
+## Advancing the time of a `TestClock`
+
+
+```C
+  #include <gst/gst.h>
+  #include <gst/check/gsttestclock.h>
+
+  GstClock *clock;
+  GstTestClock *test_clock;
+
+  clock = gst_test_clock_new ();
+  test_clock = GST_TEST_CLOCK (clock);
+  GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
+  gst_test_clock_advance_time ( test_clock, 1 * GST_SECOND);
+  GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
+  g_usleep (10 * G_USEC_PER_SEC);
+  GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
+  gst_test_clock_set_time (test_clock, 42 * GST_SECOND);
+  GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
+  ...
+```
+
+`gst::Clock` allows for setting up single shot or periodic clock notifications
+as well as waiting for these notifications synchronously (using
+`gst::Clock::id_wait`) or asynchronously (using `gst::Clock::id_wait_async` or
+`gst::Clock::id_wait_async`). This is used by many GStreamer elements,
+among them `GstBaseSrc` and `GstBaseSink`.
+
+`TestClock` keeps track of these clock notifications. By calling
+`TestClock::wait_for_next_pending_id` or
+`TestClock::wait_for_multiple_pending_ids` a unit tests may wait for the
+next one or several clock notifications to be requested. Additionally unit
+tests may release blocked waits in a controlled fashion by calling
+`TestClock::process_next_clock_id`. This way a unit test can control the
+inaccuracy (jitter) of clock notifications, since the test can decide to
+release blocked waits when the clock time has advanced exactly to, or past,
+the requested clock notification time.
+
+There are also interfaces for determining if a notification belongs to a
+`TestClock` or not, as well as getting the number of requested clock
+notifications so far.
+
+N.B.: When a unit test waits for a certain amount of clock notifications to
+be requested in `TestClock::wait_for_next_pending_id` or
+`TestClock::wait_for_multiple_pending_ids` then these functions may block
+for a long time. If they block forever then the expected clock notifications
+were never requested from `TestClock`, and so the assumptions in the code
+of the unit test are wrong. The unit test case runner in gstcheck is
+expected to catch these cases either by the default test case timeout or the
+one set for the unit test by calling tcase_set_timeout\(\).
+
+The sample code below assumes that the element under test will delay a
+buffer pushed on the source pad by some latency until it arrives on the sink
+pad. Moreover it is assumed that the element will at some point call
+`gst::Clock::id_wait` to synchronously wait for a specific time. The first
+buffer sent will arrive exactly on time only delayed by the latency. The
+second buffer will arrive a little late (7ms) due to simulated jitter in the
+clock notification.
+
+## Demonstration of how to work with clock notifications and `TestClock`
+
+
+```C
+  #include <gst/gst.h>
+  #include <gst/check/gstcheck.h>
+  #include <gst/check/gsttestclock.h>
+
+  GstClockTime latency;
+  GstElement *element;
+  GstPad *srcpad;
+  GstClock *clock;
+  GstTestClock *test_clock;
+  GstBuffer buf;
+  GstClockID pending_id;
+  GstClockID processed_id;
+
+  latency = 42 * GST_MSECOND;
+  element = create_element (latency, ...);
+  srcpad = get_source_pad (element);
+
+  clock = gst_test_clock_new ();
+  test_clock = GST_TEST_CLOCK (clock);
+  gst_element_set_clock (element, clock);
+
+  GST_INFO ("Set time, create and push the first buffer\n");
+  gst_test_clock_set_time (test_clock, 0);
+  buf = create_test_buffer (gst_clock_get_time (clock), ...);
+  gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
+
+  GST_INFO ("Block until element is waiting for a clock notification\n");
+  gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
+  GST_INFO ("Advance to the requested time of the clock notification\n");
+  gst_test_clock_advance_time (test_clock, latency);
+  GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
+  processed_id = gst_test_clock_process_next_clock_id (test_clock);
+  g_assert (processed_id == pending_id);
+  g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
+  gst_clock_id_unref (pending_id);
+  gst_clock_id_unref (processed_id);
+
+  GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
+  g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
+  buf = get_buffer_pushed_by_element (element, ...);
+  g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, latency);
+  gst_buffer_unref (buf);
+  GST_INFO ("Check that element does not wait for any clock notification\n");
+  g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
+
+  GST_INFO ("Set time, create and push the second buffer\n");
+  gst_test_clock_advance_time (test_clock, 10 * GST_SECOND);
+  buf = create_test_buffer (gst_clock_get_time (clock), ...);
+  gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
+
+  GST_INFO ("Block until element is waiting for a new clock notification\n");
+  (gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
+  GST_INFO ("Advance past 7ms beyond the requested time of the clock notification\n");
+  gst_test_clock_advance_time (test_clock, latency + 7 * GST_MSECOND);
+  GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
+  processed_id = gst_test_clock_process_next_clock_id (test_clock);
+  g_assert (processed_id == pending_id);
+  g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
+  gst_clock_id_unref (pending_id);
+  gst_clock_id_unref (processed_id);
+
+  GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
+  g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
+  buf = get_buffer_pushed_by_element (element, ...);
+  g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==,
+      10 * GST_SECOND + latency + 7 * GST_MSECOND);
+  gst_buffer_unref (buf);
+  GST_INFO ("Check that element does not wait for any clock notification\n");
+  g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
+  ...
+```
+
+Since `TestClock` is only supposed to be used in unit tests it calls
+`g_assert`, `g_assert_cmpint` or `g_assert_cmpuint` to validate all function
+arguments. This will highlight any issues with the unit test code itself.
+
+# Implements
+
+[`gst::ClockExt`](../gst/trait.ClockExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
+<!-- impl TestClock::fn new -->
+Creates a new test clock with its time set to zero.
+
+MT safe.
+
+# Returns
+
+a `TestClock` cast to `gst::Clock`.
+<!-- impl TestClock::fn new_with_start_time -->
+Creates a new test clock with its time set to the specified time.
+
+MT safe.
+## `start_time`
+a `gst::ClockTime` set to the desired start time of the clock.
+
+# Returns
+
+a `TestClock` cast to `gst::Clock`.
+<!-- impl TestClock::fn id_list_get_latest_time -->
+Finds the latest time inside the list.
+
+MT safe.
+## `pending_list`
+List
+ of of pending `GstClockIDs`
+<!-- impl TestClock::fn advance_time -->
+Advances the time of the `self` by the amount given by `delta`. The
+time of `self` is monotonically increasing, therefore providing a
+`delta` which is negative or zero is a programming error.
+
+MT safe.
+## `delta`
+a positive `gst::ClockTimeDiff` to be added to the time of the clock
+<!-- impl TestClock::fn crank -->
+A "crank" consists of three steps:
+1: Wait for a `gst::ClockID` to be registered with the `TestClock`.
+2: Advance the `TestClock` to the time the `gst::ClockID` is waiting for.
+3: Release the `gst::ClockID` wait.
+A "crank" can be though of as the notion of
+manually driving the clock forward to its next logical step.
+
+# Returns
+
+`true` if the crank was successful, `false` otherwise.
+
+MT safe.
+<!-- impl TestClock::fn get_next_entry_time -->
+Retrieve the requested time for the next pending clock notification.
+
+MT safe.
+
+# Returns
+
+a `gst::ClockTime` set to the time of the next pending clock
+notification. If no clock notifications have been requested
+`GST_CLOCK_TIME_NONE` will be returned.
+<!-- impl TestClock::fn has_id -->
+Checks whether `self` was requested to provide the clock notification
+given by `id`.
+
+MT safe.
+## `id`
+a `gst::ClockID` clock notification
+
+# Returns
+
+`true` if the clock has been asked to provide the given clock
+notification, `false` otherwise.
+<!-- impl TestClock::fn peek_id_count -->
+Determine the number of pending clock notifications that have been
+requested from the `self`.
+
+MT safe.
+
+# Returns
+
+the number of pending clock notifications.
+<!-- impl TestClock::fn peek_next_pending_id -->
+Determines if the `pending_id` is the next clock notification scheduled to
+be triggered given the current time of the `self`.
+
+MT safe.
+## `pending_id`
+a `gst::ClockID` clock
+notification to look for
+
+# Returns
+
+`true` if `pending_id` is the next clock notification to be
+triggered, `false` otherwise.
+<!-- impl TestClock::fn process_id_list -->
+Processes and releases the pending IDs in the list.
+
+MT safe.
+## `pending_list`
+List
+ of pending `GstClockIDs`
+<!-- impl TestClock::fn process_next_clock_id -->
+MT safe.
+
+# Returns
+
+a `gst::ClockID` containing the next pending clock
+notification.
+<!-- impl TestClock::fn set_time -->
+Sets the time of `self` to the time given by `new_time`. The time of
+`self` is monotonically increasing, therefore providing a `new_time`
+which is earlier or equal to the time of the clock as given by
+`gst::ClockExt::get_time` is a programming error.
+
+MT safe.
+## `new_time`
+a `gst::ClockTime` later than that returned by `gst::ClockExt::get_time`
+<!-- impl TestClock::fn wait_for_multiple_pending_ids -->
+Blocks until at least `count` clock notifications have been requested from
+`self`. There is no timeout for this wait, see the main description of
+`TestClock`.
+
+MT safe.
+## `count`
+the number of pending clock notifications to wait for
+## `pending_list`
+Address
+ of a `glib::List` pointer variable to store the list of pending `GstClockIDs`
+ that expired, or `None`
+<!-- impl TestClock::fn wait_for_next_pending_id -->
+Waits until a clock notification is requested from `self`. There is no
+timeout for this wait, see the main description of `TestClock`. A reference
+to the pending clock notification is stored in `pending_id`.
+
+MT safe.
+## `pending_id`
+`gst::ClockID`
+with information about the pending clock notification
+<!-- impl TestClock::fn wait_for_pending_id_count -->
+Blocks until at least `count` clock notifications have been requested from
+`self`. There is no timeout for this wait, see the main description of
+`TestClock`.
+
+# Deprecated
+
+use `TestClock::wait_for_multiple_pending_ids` instead.
+## `count`
+the number of pending clock notifications to wait for
+<!-- trait TestClockExt::fn get_property_start-time -->
+When a `TestClock` is constructed it will have a certain start time set.
+If the clock was created using `TestClock::new_with_start_time` then
+this property contains the value of the `start_time` argument. If
+`TestClock::new` was called the clock started at time zero, and thus
+this property contains the value 0.
+<!-- trait TestClockExt::fn set_property_start-time -->
+When a `TestClock` is constructed it will have a certain start time set.
+If the clock was created using `TestClock::new_with_start_time` then
+this property contains the value of the `start_time` argument. If
+`TestClock::new` was called the clock started at time zero, and thus
+this property contains the value 0.

docs/gstreamer-webrtc/docs.md

@@ -1,4 +1,9 @@
 <!-- file * -->
+<!-- enum WebRTCDTLSSetup -->
+GST_WEBRTC_DTLS_SETUP_NONE: none
+GST_WEBRTC_DTLS_SETUP_ACTPASS: actpass
+GST_WEBRTC_DTLS_SETUP_ACTIVE: sendonly
+GST_WEBRTC_DTLS_SETUP_PASSIVE: recvonly
 <!-- struct WebRTCDTLSTransport -->
 
 
@@ -37,6 +42,14 @@ GST_WEBRTC_ICE_ROLE_CONTROLLING: controlling
 # Implements
 
 [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
+<!-- enum WebRTCPeerConnectionState -->
+GST_WEBRTC_PEER_CONNECTION_STATE_NEW: new
+GST_WEBRTC_PEER_CONNECTION_STATE_CONNECTING: connecting
+GST_WEBRTC_PEER_CONNECTION_STATE_CONNECTED: connected
+GST_WEBRTC_PEER_CONNECTION_STATE_DISCONNECTED: disconnected
+GST_WEBRTC_PEER_CONNECTION_STATE_FAILED: failed
+GST_WEBRTC_PEER_CONNECTION_STATE_CLOSED: closed
+See <ulink url="http://w3c.github.io/webrtc-pc/`dom`-rtcpeerconnectionstate">http://w3c.github.io/webrtc-pc/`dom`-rtcpeerconnectionstate`</ulink>`
 <!-- struct WebRTCRTPReceiver -->
 
 
@@ -55,6 +68,7 @@ GST_WEBRTC_ICE_ROLE_CONTROLLING: controlling
 # Implements
 
 [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
+<!-- enum WebRTCRTPTransceiverDirection -->
 <!-- enum WebRTCSDPType -->
 GST_WEBRTC_SDP_TYPE_OFFER: offer
 GST_WEBRTC_SDP_TYPE_PRANSWER: pranswer
@@ -62,7 +76,6 @@ GST_WEBRTC_SDP_TYPE_ANSWER: answer
 GST_WEBRTC_SDP_TYPE_ROLLBACK: rollback
 See <ulink url="http://w3c.github.io/webrtc-pc/`rtcsdptype`">http://w3c.github.io/webrtc-pc/`rtcsdptype``</ulink>`
 <!-- struct WebRTCSessionDescription -->
-sdp: the `gst_sdp::SDPMessage` of the description
 See <ulink url="https://www.w3.org/TR/webrtc/`rtcsessiondescription`-class">https://www.w3.org/TR/webrtc/`rtcsessiondescription`-class`</ulink>`
 <!-- impl WebRTCSessionDescription::fn new -->
 ## `type_`
@@ -81,3 +94,26 @@ a new `WebRTCSessionDescription` from `type_`
 a new copy of `self`
 <!-- impl WebRTCSessionDescription::fn free -->
 Free `self` and all associated resources
+<!-- enum WebRTCSignalingState -->
+GST_WEBRTC_SIGNALING_STATE_STABLE: stable
+GST_WEBRTC_SIGNALING_STATE_CLOSED: closed
+GST_WEBRTC_SIGNALING_STATE_HAVE_LOCAL_OFFER: have-local-offer
+GST_WEBRTC_SIGNALING_STATE_HAVE_REMOTE_OFFER: have-remote-offer
+GST_WEBRTC_SIGNALING_STATE_HAVE_LOCAL_PRANSWER: have-local-pranswer
+GST_WEBRTC_SIGNALING_STATE_HAVE_REMOTE_PRANSWER: have-remote-pranswer
+See <ulink url="http://w3c.github.io/webrtc-pc/`dom`-rtcsignalingstate">http://w3c.github.io/webrtc-pc/`dom`-rtcsignalingstate`</ulink>`
+<!-- enum WebRTCStatsType -->
+GST_WEBRTC_STATS_CODEC: codec
+GST_WEBRTC_STATS_INBOUND_RTP: inbound-rtp
+GST_WEBRTC_STATS_OUTBOUND_RTP: outbound-rtp
+GST_WEBRTC_STATS_REMOTE_INBOUND_RTP: remote-inbound-rtp
+GST_WEBRTC_STATS_REMOTE_OUTBOUND_RTP: remote-outbound-rtp
+GST_WEBRTC_STATS_CSRC: csrc
+GST_WEBRTC_STATS_PEER_CONNECTION: peer-connectiion
+GST_WEBRTC_STATS_DATA_CHANNEL: data-channel
+GST_WEBRTC_STATS_STREAM: stream
+GST_WEBRTC_STATS_TRANSPORT: transport
+GST_WEBRTC_STATS_CANDIDATE_PAIR: candidate-pair
+GST_WEBRTC_STATS_LOCAL_CANDIDATE: local-candidate
+GST_WEBRTC_STATS_REMOTE_CANDIDATE: remote-candidate
+GST_WEBRTC_STATS_CERTIFICATE: certificate

docs/gstreamer/docs.md

@@ -693,7 +693,8 @@ Copy `size` bytes starting from `offset` in `self` to `dest`.
 ## `offset`
 the offset to extract
 ## `dest`
-the destination address
+
+ the destination address
 ## `size`
 the size to extract
 
@@ -12157,8 +12158,9 @@ outside of the segment is extrapolated.
 When 1 is returned, `running_time` resulted in a positive position returned
 in `position`.
 
-When this function returns -1, the returned `position` should be negated
+When this function returns -1, the returned `position` was < 0, and the value
-to get the real negative segment position.
+in the position variable should be negated to get the real negative segment
+position.
 ## `format`
 the format of the segment.
 ## `running_time`