Skip to content

Clarify XLALMakeTimestamps() documentation

David Keitel requested to merge david-keitel/lalsuite:clarify-XLALMakeTimestamps-documentation into master

Description

The original version is confusing IMHO:

Given a start-time, Tspan, Tsft and Toverlap, returns a list of timestamps covering this time-stretch (allowing for overlapping SFT timestamps).

NOTE: boundary-handling: the returned list of timestamps are guaranteed to cover the interval [tStart, tStart+duration), assuming a each timestamp covers a length of 'Tsft' This implies that the actual timestamps-coverage can extend up to 'Tsft' beyond 'tStart+duration'.

Here two concepts got mixed up,

  • which actual timestamps are returned,
  • which intervals are covered,

and hence it was easy to misunderstand it in such a way that tStart+duration would actually be included in the return list (in conflict with the open interval noted, and the corresponding XLALCWGPSinRange() convention). In fact it's perfectly consistent with that convention, and I hope the new text is clearer on that.

API Changes and Justification

Backwards Compatible Changes

  • This change introduces no API changes
  • This change adds new API calls

Backwards Incompatible Changes

  • This change modifies an existing API
  • This change removes an existing API

If any of the Backwards Incompatible check boxes are ticked please provide a justification why this change is necessary and why it needs to be done in a backwards incompatible way.

Review Status

@karl-wette please have a look, and @rodrigo.tenorio may also comment if this is clear enough following our discussion.

Merge request reports