Multiline comments, especially in Tcl

[John Seal]

1. Does ROBODoc handle "remark begin markers" that contain spaces?

2. Does ROBODoc ignore lines in multiline comments, unless they also start with a "remark marker"?

Here's a multiline comment using a common Tcl idiom:

if 0 {
    ****f* test/foo
    blah
    blah
    ****
}

I'm trying to get "blah blah" recognized as part of the documentation. The "header markers" and "end markers" are recognized, but the other lines aren't. ROBODoc should be able to identify them as comments, even though they don't start with a "remark maker", because they're between "remark begin markers" and "remark end markers", right?

[David White]

John,

A couple of comments
1. Robodoc documentation needs to be activated at the routine level, not for individual sections of code, so your header ****f* etc needs to be at the start of the routine and the **** at the end.
2. Unless you want Robodoc to echo the entire source to the documentation using the SOURCE keyword, the comments you want in the documentation also need to be identified as Robodoc comments.  I'm not familiar with Tcl, but I believe from the documenation, your Robodoc comments should begin with #, as should the headers, so your code would look like
#****f* test/foo
if 0 {
# blah
# blah
}
other code ...
# other comments
#****

Regards,

David

[Thuffir]

1. spaces in "remark begin markers" and "remark end markers" are handled as newlines, so they separate multiple items

2. robodoc ignores lines without "remark marker". exeption are SOURCE (and like) elements.
"remark begin markers" and "remark end markers" are merely help items and play role in SOURCE elements and in syntax highlightings

extract from robodoc documentation:

7.15.  remark begin markers and remark end markers block
Some languages allow remarks to span more than one line. They start a remark with a begin marker and end it with another marker. For instance in C you can have:

   /* This is a
      multi-line remark.
    */

Here the markers are /* and */. If you tell ROBODoc what these markers are in a remark begin markers block and remark end markers block. ROBODoc can skip them in source items.

We illustrate this with an example. Say we have a language that start a remark with |* and *|. We define SYNOPSIS to be a source like item. If we now run ROBODoc on the without a remark begin markers and end markers block on the following piece of source,

|****f* Bar/foo
* FUNCTION
*   foo computues the foo factor.
* SYNOPSIS
*|
int foo( float correction )
|*
* BUGS
*   None
* SOURCE
*|  .
{
    return correction * 42.0;
}
|*****|

the extracted documentation will look like:

FUNCTION
   foo computues the foo factor.
SYNOPSIS
   *|
   int foo( float correction )
   |*
BUGS
   None
SOURCE
   *|  .
   {
      return correction * 42.0;
   }

because ROBODoc considers |* and *|.to be part of the source, and not part of the begin or end of a header.

If you add

remark begin markers:
       |*
remark end markers:
       *|

the output will look like:

FUNCTION
   foo computues the foo factor.
SYNOPSIS
   int foo( float correction )
BUGS
   None
SOURCE
   {
      return correction * 42.0;
   }

These markers will also be used to highlight block comments if the --syntaxcolors_enable block_comments option (or the --syntaxcolors option) is specified (Similar to source line comments block).