- About Scala
- Documentation
- Code Examples
- Software
- Scala Developers
Request for @example tag for Scaladoc
Wed, 2011-05-18, 21:51
I've done a number of years as a tech writer, and nothing, absolutely _nothing_ is as important to good tech writing as examples. I'm not sure what form an @example tag should take, but here's one thought:
@example {A code snippet} optional text explanation
The braces shouldn't cause problems, I would imagine, because the code included in them is assumed to be correct and so have balanced braces. The optional text explanation would explain the result of executing the code, if such explanation was necessary. The big advantages of having such a tag are
1) It encourages people to write examples.2) The examples can be nicely formatted in the doc output to make things easier to read.
I know this is low on the totem pole, but I figured it couldn't hurt to ask.
Thanks,Ken
@example {A code snippet} optional text explanation
The braces shouldn't cause problems, I would imagine, because the code included in them is assumed to be correct and so have balanced braces. The optional text explanation would explain the result of executing the code, if such explanation was necessary. The big advantages of having such a tag are
1) It encourages people to write examples.2) The examples can be nicely formatted in the doc output to make things easier to read.
I know this is low on the totem pole, but I figured it couldn't hurt to ask.
Thanks,Ken
Wed, 2011-05-18, 22:47
#2
Re: Request for @example tag for Scaladoc
My apologies--I would've thought that the Scaladoc system would be part of the internals (after all, it pulls data from the AST). Where should I post such requests in the future?
Ken
On May 18, 2011, at 4:14 PM, Seth Tisue wrote:
>>>>>> "Ken" == Ken McDonald writes:
>
> Ken> I know this is low on the totem pole, but I figured it couldn't
> Ken> hurt to ask.
>
> It hurts when you ask on scala-internals. Ow!
>
Wed, 2011-05-18, 23:17
#3
Re: Request for @example tag for Scaladoc
>>>>> "Kenneth" == Kenneth McDonald writes:
Kenneth> My apologies--I would've thought that the Scaladoc system
Kenneth> would be part of the internals (after all, it pulls data from
Kenneth> the AST). Where should I post such requests in the future?
Kenneth> Ken
scala-language or scala-debate, I think.
http://www.scala-lang.org/node/199 has the list descriptions.
Cheers,
>>>>> "Ken" == Ken McDonald writes:
Ken> I know this is low on the totem pole, but I figured it couldn't
Ken> hurt to ask.
It hurts when you ask on scala-internals. Ow!