Merge pull request #48 from ligen131/docs-20240214-many-docs

添加若干文档，为 expr_validator 添加 enum 名 CharType

objects/block/block.gd

@@ -1,9 +1,13 @@
-extends Area2D
+## 表达式中的一个可被放入 [Card] 的卡槽，或是字符固定的一个格子。
 
-class_name Block
+class_name Block extends Area2D
 
 
-signal occupied_card_changed(block: Block) ## 当被占用的 Card 发生改变后发出。
+## 当被占用的 [Card] 发生改变后发出。
+## [br][br]
+## [param block] 为发出该信号的 [Block] 对象。
+signal occupied_card_changed(block: Block) 
+
 
 
 const SHAKE_AMOUNT := 3.0 ## 振动时的振幅（单位为像素）。
@@ -19,22 +23,22 @@ var quest_pos := -1 ## 在表达式中对应字符位置的下标。
 
 
 
-## 是否为空槽。
+## 是否为空槽，即能否被 [Card] 占用。
 func is_empty() -> bool:
 	return not self.is_fixed and self.occupied_card == null
 
 
-## 设置固定的字符为 value。
-##
-## 应当只在 is_fixed 为 true 时被调用。
+## 设置固定的字符为 [param value]。
+## [br][br]
+## 应当只在 [member is_fixed] 为 [code]true[/code] 时被调用。
 func set_word(value: String) -> void:	
 	assert(self.is_fixed, "void Block::set_word(value: String) should only be called when is_fixed is true.")
 	$Word.set_word(value)
 
 
-## 设置占用的 Card 为 card。
-##
-## 应当只在 is_fixed 为 false 时被调用。
+## 设置占用的 [Card] 为 [param card]。
+## [br][br]
+## 应当只在 [member is_fixed] 为 [code]false[/code] 时被调用。
 func set_card(card: Card) -> void:
 	assert(not self.is_fixed, "void Block::set_card(card: Card) should only be called when is_fixed is false.")
 	if self.occupied_card != card:
@@ -43,10 +47,10 @@ func set_card(card: Card) -> void:
 
 
 ## 获取当前字符。
-##
-## 当 is_fixed 为 true 时，从子节点 Word 返回固定的字符。
-##
-## 当 is_fixed 为 false 时，返回占用的 Card 的字符。
+## [br][br]
+## 当 [member is_fixed] 为 [code]true[/code] 时，从子节点 [Word] 返回固定的字符。
+## [br][br]
+## 当 [member is_fixed] 为 [code]false[/code] 时，返回占用的 [Card] 的字符。
 func get_word() -> String:
 	if self.is_fixed:
 		return $Word.get_word()
@@ -70,12 +74,13 @@ func set_is_golden_frame(value: bool) -> void:
 	$GoalFrameSprite.visible = not self.is_fixed and self.is_golden_frame
 
 
+## 若 [param v] 为 [code]true[/code]，且有占用的 [Card]，则将其设置为通关状态（即调用 [method Card.set_victory])。
 func set_victory(v: bool) -> void:
 	if v and not self.is_fixed and self.occupied_card != null:
 		self.occupied_card.set_victory(v)
 
 
-## 设置字符颜色为 value。
+## 设置字符颜色为 [param value]。
 func set_color(value: Color) -> void:
 	if self.is_fixed:
 		$Word.set_color(value)	
@@ -85,8 +90,7 @@ func set_color(value: Color) -> void:
 
 
 
-## 开始震动。
-## is_frame_red 表示是否将框改为红色。
+## 开启震动。若 [param is_frame_red] 为 [code]true[/code]，则将框改为红色。
 func shake(is_frame_red: bool) -> void: 
 	# 开启震动
 	$ShakeTimer.start()

objects/card/card.gd

@@ -1,21 +1,18 @@
-extends Area2D  
+## 写有单个字符的卡牌方块。由 [CardBase] 生成，可以被填入表达式的空格（即有空位的 [Block]）中。
+class_name Card extends Area2D  
 
-class_name Card 
 
 
-var is_dragging := false  ## 是否正在被拖拽。
-
 var current_block: Block = null ## 当前所占用的 Block 对象。
-
+var is_dragging := false  ## 是否正在被鼠标拖拽。
+var is_shaking := false  ## 是否正在震动。
 var is_victory := false  ## 是否已通关。
-
 var shake_amount : float  ## 震动幅度（单位为像素）。
-var is_shaking := false  ## 是否正在震动。
 
 
 
-## 获取当前最近的，Area 相交的，且未被占用的 Block。
-##
+## 获取当前最近的，[Area2D] 相交的，且未被占用的 [Block]。
+## [br][br]
 ## 距离按两个中心点间的距离计算。
 func get_top_prior_entered_block() -> Block:
 	var top_block: Block = null
@@ -27,8 +24,8 @@ func get_top_prior_entered_block() -> Block:
 
 
 ## 进行被拾取时的处理。
-##
-## 一般在生成 Card 时，以及鼠标移到 Card 上点击鼠标左键时调用。
+## [br][br]
+## 一般在生成 [Card] 时，以及鼠标移到 [Card] 上点击鼠标左键时调用。
 func pick_up():
 	self.z_index += 1
 	self.is_dragging = true
@@ -38,8 +35,8 @@ func pick_up():
 
 
 ## 进行被放下时的处理。
-##
-## 一般在 Card 被拖动的过程中，点击鼠标右键时调用。
+## [br][br]
+## 一般在 [Card] 被拖动的过程中，点击鼠标右键时调用。
 func put_down(): 
 	self.z_index -= 1
 	var entered_block := get_top_prior_entered_block()
@@ -56,11 +53,9 @@ func put_down():
 		queue_free()	
 
 
-## 使 Card 开始震动。
-##
-## * is_letter_red：是否要将字符颜色改为红色
-## * amount：震动幅度
-## * duration：震动持续时长
+## 使 [Card] 开始震动。 [param amount] 和 [param duration] 为震动幅度和震动持续时间。
+## [br][br]
+## 若 [param is_letter_red] 为 [code]true[/code]，则将字符颜色改为红色。
 func shake(is_letter_red: bool, amount: float, duration: float) -> void:
 	$ShakeTimer.wait_time = duration
 	self.shake_amount = amount
@@ -75,18 +70,18 @@ func shake(is_letter_red: bool, amount: float, duration: float) -> void:
 		$HighlightSprite.visible = false
 
 
-## 设置字符颜色。
-func set_color(value: Color) -> void:  # 设置颜色函数
+## 设置字符颜色为 [param value]。
+func set_color(value: Color) -> void: 
 	$Word.set_color(value)  # 设置文字颜色
 
 
-## 设置是否为胜利状态。
-func set_victory(v: bool):  # 设置胜利状态函数
+## 若 [param v] 为 [code]true[/code]，则进行通关时的处理。
+func set_victory(v: bool): 
 	if v:
 		$CollisionShape2D.set_deferred("disabled", true)  # 如果胜利，禁用碰撞形状
 
 
-## 设置字符为 value，同时更新卡背颜色。
+## 设置字符为 [param value]，同时更新卡背颜色。
 func set_word(value: String) -> void:
 	$Word.set_word(value) 
 	var card_type := "card-%s" % ExprValidator.get_char_type_as_str(get_word()).to_lower()  # 根据单词类型获取卡牌类型
@@ -130,7 +125,7 @@ func _input_event(_viewport: Object, event: InputEvent, _shape_idx: int) -> void
 		if event.button_index == MOUSE_BUTTON_LEFT:
 			if event.is_pressed(): # 如果按下左键，则拾取 Card
 				pick_up()
-			elif self.is_dragging: # 否则则是放开左键，此时若 Card 正在拖拽，则放下
+			elif self.is_dragging: # 否则则是放开左键，此时若 [Card] 正在拖拽，则放下
 				put_down()
 
 		elif event.button_index == MOUSE_BUTTON_RIGHT and event.is_pressed():  # 按下右键时

objects/word/word.gd

@@ -1,68 +1,85 @@
-extends AnimatedSprite2D
+## 单个字符的动画，可自定义颜色。
+class_name Word extends AnimatedSprite2D
 
 
-class_name Word
 
 
+## 显示的字符下标。
+## [br][br]
+## 当前显示的字符应为 [code]LETTER_NAME[text_id][/code]。
+@export var text_id := 0 
 
-@export var text_id := 0
-@export var color := Color.BLACK
+@export var color := Color.BLACK ## 当前字符颜色。
 
 
-const STEP := 30
+const STEP := 30 ## 在字符动画的资源文件夹（[code]res://objects/word/sprites[/code]）中，同一个字符相邻帧之间的文件编号差。
 const LETTER_NAME = [" ", "=", "P", "b", "D", 
 "I1", "I2", "I3", "I4", "I5", 
 "R", "Q", "d", "q", "(",
 "*", "+", "<", ">", ")",
 "0", "1", "2", "3", "4",
-"5", "6", "7", "8", "9"]
+"5", "6", "7", "8", "9"] ## 可取的字符列表。
 
 
-## 内建，不要用。
+## 获取字符 [param letter] 在 [member LETTER_NAME] 中对应的下标。
+## [br][br]
+## 若不存在，返回 [code]-1[/code]。
 func get_letter_id(letter: String) -> int:
 	for i in range(len(LETTER_NAME)):
 		if LETTER_NAME[i] == letter:
 			return i
-	assert(false, "Letter " + letter + " not found")
+	push_warning("Letter %s not found in LETTER_NAME." % letter)
 	return -1
 
 
-## 内建，不要用。
+## 设置 [member text_id] 为 [param value] 并更新动画。
 func set_text_id(value: int) -> void:
 	assert(value >= 0, "text id < 0")
 	text_id = value
 	update_animation()
 
+
+## 根据当前的 [member text_id] 更新动画。
 func update_animation() -> void:
 	ImageLib.update_animation(self, text_id + 1, 3, STEP, "res://objects/word/sprites/sprite%d.png", Color.BLACK, color)
 
 
 
-## 更改字母为 text。
+## 设置字符为 [param text]。
+## [br][br]
+## [b]注意[/b]：若 [param text] 为 [code]_[/code] 或 [code].[/code]，则会设置为 [code] [/code]。但不推荐使用该做法。
 func set_word(text: String) -> void:
 	if text == "_" or text == ".":
+		push_warning("set_word(%s) is not recommended." % text)
 		set_text_id(0)
 	else:
 		set_text_id(get_letter_id(text))
 
-## 获得当前字母。
+
+## 获取当前字符。
 func get_word() -> String:
 	return LETTER_NAME[text_id]
 
 
-func _ready():
-	update_animation()
-
+## 设置字符颜色为 [param value] 并更新动画。
 func set_color(value: Color) -> void:
 	color = value
 	update_animation()
 
+
 ## 设置是否为关卡通过状态。
-## 已弃用，请使用 set_color 或 set_color_from_name 代替。
+## [br][br]
+## 将废弃，请使用 [method set_color] 代替。
+## [br][br]
 ## @deprecated
 func set_victory(v: bool) -> void:
 	push_warning("void set_victory(v: bool) is deprecated.")
 	if v:
 		set_color(ImageLib.PALETTE["golden"])
 	else:
 		set_color(ImageLib.PALETTE["default"])
+
+
+
+func _ready():
+	update_animation()