Comments

Lexer
LINE_COMMENT :
      ;; (~[; !] | ;;) ~\n*
   | ;;

BLOCK_COMMENT :
      #| (~[# |] | || | BlockCommentOrDoc) (BlockCommentOrDoc | ~|#)* |#
   | #||#
   | #|||#

INNER_LINE_DOC :
   ;;! ~[\n IsolatedCR]*

INNER_BLOCK_DOC :
   #|! ( BlockCommentOrDoc | ~[|# IsolatedCR] )* |#

OUTER_LINE_DOC :
   ;;; (~/ ~[\n IsolatedCR]*)?

OUTER_BLOCK_DOC :
   #|| (~| | BlockCommentOrDoc ) (BlockCommentOrDoc | ~[|# IsolatedCR])* |#

BlockCommentOrDoc :
      BLOCK_COMMENT
   | OUTER_BLOCK_DOC
   | INNER_BLOCK_DOC

IsolatedCR :
   A \r not followed by a \n

Non-doc comments

The syntax of comments in Oxur follow the general Common Lisp style, but the meaning is not the same. Rust has a specific set up line and block comments serve different purposes. Oxur comments follow that closely.

Doc comments

Line doc comments beginning with exactly three semi-colons (;;;), and block doc comments (#|| ... |#), both inner doc comments, are interpreted as a special syntax for doc attributes. That is, they are equivalent to writing #[doc "..."] around the body of the comment, i.e., ;;; Foo turns into #[doc "Foo"] and #|| Bar |# turns into #[doc "Bar"].

Line comments beginning with ;;! and block comments #|! ... |# are doc comments that apply to the parent of the comment, rather than the item that follows. That is, they are equivalent to writing #![doc "..."] around the body of the comment. ;;! comments are usually used to document modules that occupy a source file.

Isolated CRs (\r), i.e. not followed by LF (\n), are not allowed in doc comments.

Examples

;;! A doc comment that applies to the implicit anonymous module of this crate

(pub mod outer_module

    ;;!  - Inner line doc
    ;;!! - Still an inner line doc (but with a bang at the beginning)

    #|!  - Inner block doc |#
    #|!! - Still an inner block doc (but with a bang at the beginning) |#

    ;;   - Only a comment
    ;;;  - Outer line doc (exactly 3 slashes)
    ;;;; - Only a comment

    #|   - Only a comment |#
    #||  - Outer block doc (exactly) 2 asterisks |#
    #||| - Only a comment |#

    (pub mod inner_module)

    (pub mod nested_comments 
        #| In Oxur #| we can #| nest comments |# |# |#

        ;; All three types of block comments can contain or be nested inside
        ;; any other type:

        #|   #| |#  #|| |#  #|! |#  |#
        #|!   #| |#  #|| |#  #|! |#  |#
        #||!   #| |#  #|| |#  #|! |#  |#
        (pub mod dummy_item)
    }

    (pub mod degenerate_cases
        ;; empty inner line doc
        ;;!

        ;; empty inner block doc
        #|!|#

        ;; empty line comment
        ;;

        ;; empty outer line doc
        ;;;

        ;; empty block comment
        #||#

        (pub mod dummy_item)

        // empty 2-asterisk block isn't a doc block, it is a block comment
        #|||#

    }

    #| The next one isn't allowed because outer doc comments
       require an item that will receive the doc |#

    ;;; Where is my item?
}