diff --git a/DOCS/write-preview-skeleton.md b/DOCS/write-preview-skeleton.md new file mode 100644 index 0000000..19d984b --- /dev/null +++ b/DOCS/write-preview-skeleton.md @@ -0,0 +1,82 @@ +# 关于编写 "描述主体结构预览说明" 的规范 + +1. 主体结构预览 + + 一般以 `tree` 命令进行获取目录结构进行展示所需要描述的预览内容。 + +2. 对主体结构中的内容单独说明 + + 并使用所用语言进行非侵入式独立描述,而不是在代码中填充说明与注释。 + + 在单行描述中,尽量不超过您认为最大的字符数量宽度,可以收缩内容的重要性。 + + 在此种说明文档中,尽量使用您所描述的对象支持的代码注释,而不是以白底黑字进行描述。 + + 对于规范的全部:主体结构 + 单独内容中进行简单(而不是简少)的说明。 + +一个简单的例子,例如: 有关项目源代码结构的预览说明 + +- 项目结构预览 + + ``` + . + ├── assets + ├── debian + ├── DOCS + ├── patchs + ├── src + ├── tool + └── translations + + 10 directories, 9 files + ``` + +- 来自 debian 目录的说明 + + ```shell + # 将此项目进行 debian 的标志,基于 debian 系列的发行版可对包含 + # 此种目录的开源项目进行构建 deb 软件包。 + + # 1. 构建软件包(打包) + # 执行 dpkg-buildpackage 命令以尝试构建此软件包 + dpkg-buildpackage + # 如果构建将会在上级目录中产生一个 deb,而源代码目录不会有任何变化。 + + # 如果出现以下内容可忽视,仅需要查看是否已成功构建软件包: + # gpg: 已跳过 "": 无效的用户ID + # gpg: ...: clear-sign failed: 无效的用户ID + # dpkg-buildpackage: error: failed to sign .dsc file + ``` + +- 来自 patchs 目录的说明 + + ```shell + # 一种用于可扩展的补丁,主要目的是为项目提供可选的应用方案,而不是直接堆砌到 + # 当前项目的分支中。您可以认为所有分支都是主线分支。 + # 例如: + # 主线稳定分支: master + # 主线开发分支: dev + # 主线其它: ... + + # 注意: + # 当您认为您所提交的内容并不会为主线带来 bug fix 之类的内容,请使用补丁。 + # 当您所提交的内容会带来不可预知的问题的时候,或会改变目前主线的开发模式时, + # 此种方式可确保您提交的方案可被任意时间被弃用,而不是由其它维护者耗费精力 + # 去试图移除您提交的内容,而不是等待由提交者进行新的维护。 + ``` + +- 来自其它的内容...可随时由任何人进行补充 + + +- 一些在关此种预览描述的文档 + + ```shell + # 此种描述还将出现在 `src/README.md` 的描述中。 + # 当然,我预期会由其它维护者进行移动到 `DOCS` 之下。 + + # 另外在 `patchs/zinface-community-cmake-build-system.patch` 补丁文件中, + # 也随附过一个简要的文档内容,而它是记录了 `Spark` 为名的构建模式。 + + # 在未应用此补丁时,将不会出现在任何地方。 + ``` + \ No newline at end of file diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..4e9e490 --- /dev/null +++ b/src/README.md @@ -0,0 +1,30 @@ +# 有关 src 下的一些改进预览 + +> 1. 主体结构预览 +> 2. 主体结构中的内容单独说明 +> 并使用所用语言进行非侵入式独立描述,而不是在代码中填充说明与注释。 +> +> 这是简单的预览说明规范 + +- widget/base 结构 + + ``` + src/widgets/base/ + ├── basewidgetopacity.cpp + └── basewidgetopacity.h + + 0 directories, 2 files + ``` + +- 来源于 widget/base 的说明 + + ```c++ + // BaseWidgetOpacity 是一个提供了淡出/淡入动画的基础类: + // 1. closeEvent 窗口关闭时进行淡出动画 + // 此前在 MainWindow 中实现的淡出动画将由 BaseWidgetOpacity 来实现。 + + // 此前 MainWindow 原有的 DBlurEffectWidget 父类将移交至 BaseWidgetOpacity 继承。 + + // 注意: + // 如果 MainWindow 在未来重写 closeEvent 事件时将可能丢失 BaseWidgetOpacity 中的淡出效果 + ``` \ No newline at end of file