comments in examples

Comments are sometimes stripped from examples, and sometimes they aren't. The behavior is also different between generated exampled and canned examples.

Consider the simple package below:

newPackage("Foo", Headline => "foo")

export {"foo"}

foo = () -> print "foo"

beginDocumentation()

doc ///
 Key
   foo
 Description
   Text
     Regular example
   Example
     -- foo
     elapsedTime 2 + 2
  Text
    Canned example
  CannedExample
    i1 : -- foo
         elapsedTime 2 + 2
     -- 3.33e-6 seconds elapsed

    o1 = 4
///

This gives us:

i3 : help "foo"

o3 = foo
     ***

     Description
     ===========

     Regular example

     +--------------------------+
     |i1 : elapsedTime 2 + 2    |
     | -- 3.5e-7 seconds elapsed|
     |                          |
     |o1 = 4                    |
     +--------------------------+

     Canned example

     +----------------------+
     |i1 : -- foo           |
     |     elapsedTime 2 + 2|
     |                      |
     |o1 = 4                |
     +----------------------+

     For the programmer
     ==================

     The object "foo" is a function closure.

o3 : DIV

Reproduce the issue using the package and documentation example shown in the report, then inspect the paths that render generated and canned examples for help "foo". Compare how each path handles the -- foo comments. Done means comment behavior is consistent between both example types and the displayed output matches the intended documentation.