3

In our Scala code we have many trace statements that users may need to understand, so naturally we'd like to document them. Ideally, we should be able to document them in the code itself, and automatically create the documentation from the source code.

The trace strings do not need to be localized, so I would prefer to embed them in the source itself and not place them in a resource file to begin with.

Currently a typical line may read:

trace("value for x is %s" format x)

What I'd like it to be is something like this (though this is a simple example)

trace("value for x is %s" format x) //displays the value of [business name for x]

And then have a tool auto-generate the documentation by parsing the source files and outputting the trace information along with the documentation.

I imagine that it could be done by using annotations and running a custom tool on the source, but I've never done something quite like that before, and would appreciate suggestions.

4

1 回答 1

0

我认为没有任何工具可以做到这一点，但你可以写一个：

val TRACE = "[ \t]*trace *\\((.*)\\) *//(.*)".r

case class Trace(expression: String, comment: String)

def documentFile(file: String): List[Trace] = {
  io.Source.fromFile(file).lines.flatMap{
    case TRACE(e,c) => Some(Trace(e,c))
    case _          => None
  }.toList
}

您已经遍历了所有源文件，然后您可以将Trace实例转换为您想要的任何输出格式。

当然，它假定trace表达式在自己的行中并且不进行任何后处理，但这应该是一个好的开始。

于 2013-09-17T14:24:08.590 回答