内部源代码文档 - FiM ++

时间:2013-01-17 00:29:01

标签: documentation programming-languages comments javadoc code-documentation

FiM ++程序的结构要求以特定方式结束字母和代码作者姓名结束。

Dear Princess Celestia and Stack Exchange and String: A Sample:
    ...
Your faithful student, Southpaw Hare!

根据language specification,关键字"您的忠实学生," (包括逗号但不包括以下空格)用作类定义的结束标记,以下名称是没有语法效果的注释。

在每个文件中自动包含作者(如果不是严格要求)的事实让我想知道它是否可以用作类似于Java Docs的可解释文档的形式。换句话说,其他程序或编辑器将能够解析此名称并以某种方式使用它。

  1. 此类内部基于评论的文档的要求是什么?这种特殊类型的语法中是否有任何会导致问题的内容?

  2. 关键字是否足以适应主题?在我看来,缺乏使用"你忠实的学生的能力,"对于一个复数形式(或者可能"你的忠实,"或者#34;你的真实,"对于一个模糊的版本)会使多个作者的列表看起来笨拙和不自然(看起来像一个自然的人文信是核心设计范式之一。)

  3. 如果考虑创建Java Docs方法,那么还应该包含哪些其他功能?首先,日期似乎很常见。在信件顶部包含某种形式的日期评论可能看起来很自然,并且不会违背设计范例。

  4. 由于语言是新的,对大多数人来说都不熟悉,而且说实话非常愚蠢,这里有一些资源需要考虑:

    Original Release Announcement

    October Followup

1 个答案:

答案 0 :(得分:2)

对不起,在我之前没有人给予任何关注! 我正在开发这门语言,所以我觉得我对这个答案很了解。

  
      
  1. 此类内部评论的要求是什么?   文档?这种特殊类型有什么吗?   会导致问题的语法?
  2.   

我从未考虑像Javadoc这样的自动文档技术,所以没有正式的语法。我正在编写的编译器完全丢弃了注释,所以它不会支持它,但我相信它不会非常难。

  
      
  1. 关键字是否足以适合主题?它发生在我身上   认为缺乏使用“你的忠实学生”的能力   复数形式(或可能是“你的忠实”,或“你的真实”,对于一个   暧昧的版本)会使多个作者的列表看起来很尴尬   并且不自然(看起来像一个自然的小马写的信是一个   核心设计范例)。
  2.   

最后一行中作者姓名的想法是针对报告的最重要作者,因此之前从未建议多位作者。但是,Your faithful students,可以很好地工作!

  
      
  1. 如果考虑创建Java Docs方法,那么还有其他方法   功能应该包括在内?首先,日期似乎很常见。包含   这封信的顶部可能会有某种形式的日期评论   看起来自然而不是违背设计范例。
  2.   

事实上!也许是报告 bottom 的内容,比如

(Written 2013-04-11)

希望这对你有所帮助。你也有一些好主意!你应该加入这个团队!

相关问题