MS RFC 132：更新MapScript API文档¶
- 日期
2020-05-29
- 作者
塞思吉尔文
- 联系
- 状态
正在进行中
- 最后更新
2020-06-17
- 版本
MapServer 8.0版
概述¶
这个RFC建议在https://mapserver.org/mapscript/mapscript.html上添加更新当前的MapScriptAPI文档，而PHPMapScrip移动到正确的API文档变得越来越重要。
当前的MapScript API文档当前是手动更新的。它包含许多遗留方法，缺少较新的方法，并且完全缺少某些类的文档。
此RFC提议使用 SWIG's autodoc 和文档字符串功能，以及Sphinx来更新MapScrip API文档。
以下是指向示例输出的链接：
API Index Page -使用几个样例类
Generated stub for classObj -带有样例图像的示例代码
功能¶
属性类似于其相关的映射文件文档，以避免重复并减少维护(因此成为可能 Sphinx pull request )。
SWIG Python绑定可以自动生成类型提示，而Sphinx又可以链接这些类型提示以自动记录函数参数，并将它们链接到相关对象
在代码中包含注释将提高更新MapScript文档的机会
记录Python绑定还将帮助IDE自动完成，并在使用Python映射脚本库时提供帮助。
建议的方法¶
在SWIG界面(I)文件中记录所有SWIG功能
使用doxygen样式的注释将所有属性记录在可供SWIG使用的结构中
在每个MapServer版本中，都会将一个源码版本的PythonMapScript绑定推送到 PyPI -请参阅https://github.com/MapServer/MapServer/pull/6011
MapScript 将添加到文档中 requirements.txt 因此，在自动构建文档时会下载绑定。Mocks将用于导入不需要MapServer的C++MapScript扩展。
狮身人面像的扩展 autodoc 和 autosummary 将用于从Python绑定生成最新的MapScriptAPI信息
自动汇总 类模板将用于在需要的地方添加更多散文、示例和图像
可能存在的缺陷¶
对于非开发人员来说，更新代码注释可能会更困难--然而，当前的方法和建议的方法都需要Git知识
DOCS方法与GDAL方法不同(参见https://lists.osgeo.org/pipermail/mapserver-dev/2020-May/016191.html)上的注释，它不需要对头文件进行SWIG更改。
头文件将需要编辑以允许添加注释。这些注释将是doxygen样式的注释，格式为/注释和/<尾随注释
向后兼容性问题¶
对头文件的更改将破坏ABI兼容性，因此此更新是发行版(次要或主要)的一部分。
在添加文档时，可能有一些结构字段被设置为不可变或对SWIG隐藏，而这些结构字段本应已被隐藏，例如，请参见https://github.com/MapServer/MapServer/pull/5938
文件需求¶
没有超过这个RFC的。
文件夹¶
MAPSCRIPTS/SWIGINC中的.I文件
.h文件以记录结构属性
Docs项目中的conf.py、requirements.txt文件
票号和参考号¶
投票历史¶
+1来自Mikes、TomK、JeromeB、JukkaR、JeffM、DanielM、SteveL、EvenR、TamasS、SethG