hunting/doc/markdown_user_guide.md

1. Markdown使用手册

1.1. 概述

使用markdown编辑开发文档有以下好处：

• markdown语法是一种语言，类似代码一样可以方便git管理，查看修改记录；
• 对代码显示支持良好；
• 可以进行UML类图和时序图的编辑/迭代/维护（强烈推荐）；

1.2. 如何使用Markdown

此处介绍基于vscode编辑环境下使用Markdown的方法：

• 首先安装vscode插件：
  1. Markdown All in One
  2. Markdown Preview Enhanced
• 使用Markdown语法编辑开发文档，并使用vscode预览；
• 右键使用浏览器打开并打印可生成PDF文档；

1.3. 基本语法介绍

提供常用语法参考，直接copy模块代码进行编辑。

1.3.1. 常用命令

Markdown All in One: Create Table of Contents 创建目录
Markdown All in One: Update Table of Contents 更新目录
Markdown All in One: Add/Update section numbers 添加 / 更新章节编号
Markdown All in One: Remove section numbers 删除章节编号
Markdown All in One: Toggle code span 触发设置代码范围（`code`）
Markdown All in One: Toggle code block 触发设置代码块(```codes```)
Markdown All in One: Print current document to HTML
Markdown All in One: Toggle math environment 触发设置数学环境
Markdown All in One: Toggle list 触发设置列表环境

1.3.2. 代码段

/*This is your code.*/
#include <stdio.h>
int main()
{
    return 0;
}

1.3.3. UML类图语法

classDiagram
      Animal <|-- Fish:继承
      Animal <|.. Zebra:实现
      Animal : +int age
      Animal : +String gender
      Animal: +isMammal()
      Animal: +mate()
      class Animal{
        <<interface>>
        +call() int
      }
      class Fish{
          -int sizeInFeet
          -canEat()
      }
      class Zebra{
        <<class>>
          -func(int, int) int
          +bool is_wild
          +run(void)
      }

实现：一般指对抽象类的实例类
继承：一般指对普通功能基类的派生/重载

1.3.4. UML时序图

sequenceDiagram
Alice->>+Jhon:Call function
Jhon->>Jhon:handle
Jhon-->>-Alice:Call return
note left of Alice:function

Alice->>+Jhon:Call function
Jhon->>+Fancy:Call
Fancy-->>-Jhon:Call return
Jhon-->>-Alice:Call return

Alice->>+Jhon:Call function
Jhon->>+Fancy:Call
Fancy->>-Fancy:End
Jhon-->>-Alice:Call return

1.3.5. 踩坑记录

1. 状态图不能使用default关键字作为一个状态名称，无法画图；