The Racket Reference阅读笔记。

2 Notation for Documentation

2.1 Notation for Module Documentation

racket按照模块组织代码。文档会在开头标明相应的模块。

(require racket/list)

或者

#lang racket/base

后者表明模块通常是作为语言使用的。

在文档开头或者章节开头的模块定义，在子模块中也可见。

2.2 Notation for Syntactic Form Documentation

句构形式都会配有相应的语法，例如下面是给if的语法：

(if test-expr then-expr else-expr)

每个句形都表示成句构对象。括弧表示句构对象是一个连对。按照约定，有时候会使用方括号而不是括弧。

语法中的斜体标识符用来表示元变量，即为其他语法所生成的对象：

  • id结尾的元变量表示标识符
  • keyword结尾的表示句构对象的关键字
  • expr结尾的表示任意形式的表达式
  • body结尾的表示任意形式的局部定义或者表达式，定义必须出现在表达式之前，body必须以表达式收尾
  • datum结尾可以表示任意形式，但不会被解读
  • number或者boolean结尾的表示句构对象的数字或者布尔值。

如果语法中的元变量自身没有语法定义，则会在语法之后注出，例如：

(lambda formals body ...+)

 
formals	 	=	 	id
 	 	|	 	(id ...)
 	 	|	 	(id ...+ . rest-id)

一些句型构造如果有多种顶层语法，则按以下方式表示：

(init-rest id)
(init-rest)

一些语法也会为某些元变量指定合约，例如：

(parameterize ([parameter-expr value-expr] ...)
  body ...+)
 
  	parameter-expr	 	:	 	parameter?

2.3 Notation for Function Documentation

执行诀和其他值的记述形式基于合约：

(char->integer char) → exact-integer?

  char : char?

合约只是用来表明设计目的，具体的执行诀并不一定真会以合约来检查调用参数。

语法中也会体现可选参数，如下所示：

(read [in]) → any

  in : input-port? = (current-input-port)

当然，语法中也可以体现关键字：

(sort	 	lst	 	 	 	 
 	 	less-than?	 	 	 	 
 	 [	#:key extract-key	 	 	 	 
 	 	#:cache-keys? cache-keys?])	 	→	 	list?
  lst : list?
  less-than? : (any/c any/c . -> . any/c)
  extract-key : (any/c . -> . any/c) = (lambda (x) x)
  cache-keys? : boolean? = #f

2.4 Notation for Structure Type Documentation

结构类型也可以按照合约方式记述：

(struct color (red green blue alpha))

  red : (and/c natural-number/c (<=/c 255))
  green : (and/c natural-number/c (<=/c 255))
  blue : (and/c natural-number/c (<=/c 255))
  alpha : (and/c natural-number/c (<=/c 255))

2.5 Notation for Parameter Documentation

动参也是按照函数的方式记述的：

(current-command-line-arguments) → (vectorof string?)

(current-command-line-arguments argv) → void?
  argv : (vectorof (and/c string? immutable?))

动参既可以被读取，又可以被设置。

2.6 Notation for Other Documentation

有一些库提供到常量值的绑定，比如：

object% : class?

（本篇完）