Embedded documentation

Here is an example SPLDOC comment on a composite operator definition:

 /** Short sentence summarizing what the composite operator does.
     Longer description of the operator's functionality and purpose.
   @input   G description of input stream G
   @input   H description of input stream H
   @param   Q description of parameter Q
   @output  K description of output stream K
   @output  L description of output stream L
 */
 composite M (output K, L; input G, H) {
   param operator $Q;
   graph stream<int32 x> I = Functor(G)    { /*..O..*/ }
         stream<int32 x> J = Functor(H)    { /*..P..*/ }
         stream<int32 x> K =      $Q(I; J) { }
         stream<int32 x> L = Functor(J)    { /*..R..*/ }
 }

The comment is semi-structured into optional clauses with labels such as @input G or @param Q. These clauses can be consumed by other SPL-related tools. For example, Streams Studio uses the @input, @param, and @output clauses to display documentation on a composite operator's interface.

Here is an example SPLDOC comment on an operator invocation:

/** A high/low filter
 stream to be split and filtered
  @param loFilter boolean expression for low filter
  @param hiFilter boolean expression for highfilter
  @output  Lo  stream with tuples matching loFilter expression
  @output  Hi  stream with tuples matching hiFilter expression
*/
composite LoHiSplitter(output Lo, Hi; input I) {
  param expression<boolean> $loFilter;
        expression<boolean> $hiFilter;
  graph stream<int32 x> Lo = Filter(I) { param filter : $loFilter; }
        stream<int32 x> Hi = Filter(I) { param filter : $hiFilter; }
}
composite Main {
  graph
    stream<int32 x> I = Beacon() { }
    /** Split into streams of low and high values.
        The threshold value is 100: values under 100 are considered
        low, values of 100 or above are considered high.
      @input  I  stream with all values, including both low and high
      @output Lo stream with values below 100 only
      @output Hi stream with values above 100 only
    */
    (stream<int32 x> Lo; stream<int32 x> Hi) = LoHiSplitter(I) {
      param loFilter : x < 100;
            hiFilter : x >= 100;
    }
}