Document drracket:comment-delimiters

drracket/info.rkt

@@ -67,7 +67,7 @@
 
 (define pkg-authors '(robby))
 
-(define version "1.14")
+(define version "1.15")
 
 (define license
   '(Apache-2.0 OR MIT))

drracket/scribblings/tools/lang-tools.scrbl

@@ -161,6 +161,37 @@ The default value is @racket[(list #\" #\|)].
  @history[#:added "1.10"]
 }
 
+@section{Comments}
+
+@language-info-def[drracket:comment-delimiters]{
+
+ When a language's @racket[_get-info] procedure responds to
+@racket['drracket:comment-delimiters], it is expected to return a list
+of comment styles. Each comment style is expressed as a list of three
+strings:
+
+ @itemlist[
+
+  @item{The characters used to start/open a comment.}
+
+  @item{The characters used to end/close a comment. May be @litchar[""] to mean newline.}
+
+  @item{Padding to add after the start and before the close.}
+ ]
+
+ These values are used by comment and un-comment commands.
+
+ The default value is @racket[(list (list ";;" "" " ") (list "#|" "|#" " "))].
+
+ When the list has multiple styles, some tools may present them for
+the user to pick one. Other tools may default to using the first style
+in the list (the user will configure a preference by others means).
+Therefore when a language supports multiple comment styles, it should
+list the most popular or preferred style first.
+
+ @history[#:added "1.15"]
+}
+
 @section{Keystrokes}
 
 @language-info-def[drracket:keystrokes]{