项目文档

罗丹

活跃成员
已加入
2015年4月7日
留言内容
41
编程经验
10+
这似乎不适合任何现有论坛,因此我将在此处盲目发布,希望我不会被打得太糟。

我正在为Raspberry开发一个名为PiIO的GPL C#IO库,而我正在尝试做的是记录我进行中的所有内容,而不是完成项目并放弃,因为事后编写文档的工作量很大。问题是,以一种对我本人以外的人有意义的方式来布局文档的结构时,我有点无所适从。我已经尝试搜索示例,但是我得到的只是关于如何使用Product X创建文档的模糊描述,而没有任何有关如何记录代码的真实示例。

我决定使用gitHub Wiki而不是使用大量的自述文件,尽管我可能也会有很多。我遇到过许多无法导航的Wiki,但我想避免这样做。我希望您能对您认为做得很好的记录Wiki示例代码的代码提出一些建议或链接。

我正在考虑将文档按名称空间划分,这将产生如下的TOC:

C#:
* PiIO
  * GPIO
  * I2C
  * SPI
.. etc

在其中一个链接上单击将显示名称空间的该部分中的所有内容,例如Methods,enums等。例如,点击I2C将显示

C#:
I2C Methods and properties

Class I2CCmd 

Properties:
None

Methods:

I2CCmd.Init()
  Success: Linux File Handle
  Error: Negative int

  PiIO uses Linux file handles to talk to I2C devices, not the device's I2C address.
    
  Example: deviceHandle = I2CCmd.Init(I2CAddress);

<More methods and properties>

真的不知道这是否是显示名称空间中内容的好方法。

另外(如果我能弄清楚如何)将TOC范围扩展到I2C,以显示其子级,例如:

C#:
PiiO
  * I2C
    * Devices
      * ADC
      * DAC
      * Sensors

我可以一直让TOC始终显示所有名称空间和子名称,但是我个人觉得很难导航。

人们怎么看?更好的想法或示例链接?

谢谢!
 

罗丹

活跃成员
已加入
2015年4月7日
留言内容
41
编程经验
10+
是的,把我所有的"///"自动评论全部填写完毕。当我走的时候总是那样做,所以不会真的感觉像我"documenting" rather than coding.
 

金西尼

C#论坛主持人
工作人员
已加入
2011年4月23日
留言内容
3,523
地点
悉尼,澳大利亚
编程经验
10+
一段时间以来,这并不是我真正研究过的主题,但过去一直有很多关于Sandcastle的讨论,Sandcastle是Microsoft自己完成任务的工具集。就简单性而言,我不确定它是否已经成为很多人希望的,并且我不确定是否有比此更高的版本:

//www.microsoft.com/en-us/download/details.aspx?id=10526
 

罗丹

活跃成员
已加入
2015年4月7日
留言内容
41
编程经验
10+
我尝试了一下,它产生了非常不错的文档。没有啦"home"页面在输出中,但是我想那是因为我应该通过某种特殊的查看器加载它。昨晚并没有深入探讨它,因为我发现MS版本已被放弃,现在是开源的。我抓取了包括markdown的较新版本(我认为对github wiki很好)。尝试了一种快速工具-不阅读文档-开枪射击,但是一无所获。今天早上要阅读文档。

希望它不像Doxygen那样不透明-不能使该方法无效。
 
最佳 底部