On 2014-09-08 20:32, Wil Cooley wrote:
On Aug 8, 2014 5:15 PM, "Hailee Kenney" <hai...@puppetlabs.com
<mailto:hai...@puppetlabs.com>> wrote:
>
> Right now, Charlie Sharpsteen has an awesome prototype which uses
YARDoc instead of RDoc.
I see that "YARD does not impose a specific markup"[1] and I cannot tell
from Charlie's prototype which markup is intended -- I would hope that
one of them would be picked as a standard and I would be happiest with
something that uses some flavor of Markdown.
So far, the idea has been to standardize on a particular preferred
markup based on Markdown with a selection of tags from yardoc. In order
to no force everyone that has invested in writing RDoc documentation to
rewrite all docs in their manifests, we also need to continue supporting
this. However, note that the support for any kind of markup in the
current puppet doc tool is very very limited, and it is really only this
limited set that will be supported going forward. Therefore there is
typically not much markup at all in documentation.
I expect us to exactly specify the markdown and tagging that the new
"puppet doc" tool will support. IMO this specification will be
compatible with Markdown (some defined flavor) and yardoc tags.
I understand that more semantic markup is desired, but I find the
proliferation of wildly incompatible text markup formats frustrating.
Variations in Markdown implementations[2] are bad enough; having to
mentally switch to RDoc format to write module documentation causes much
wailing and gnashing of teeth.
Is this intended to be used only in Puppet manifests, or would there be
support (in tooling/standards, at least) for using it in Ruby exentions too?
Yes, Since the idea is to be Markdown/Yard compatible.
I would also like to express my concern about: "Documentation blocks
must immediately precede the documented code with no whitespace." -- I
spent several hours that could better have been spent watching Vanilla
Sky or Gigli to this little bundle of joy in the current implementation
-- particularly the "with no whitespace" bit.
Yeah, hate that for two reasons; a) you may accidentally get
documentation output when you intended a comment, and b) the
documentation may not show up if there is a blank space.
We no longer have to have this rule. It has also been proposed that
comments sequences that start with ## are special. This is important
since it is also proposed that it should be possible to document
parameters on the same line (after the declared element). say
foo ## This is doc for foo
Here the ## are needed if we want it to be possible to write a comment
that is not documentation.
- henrik
--
Visit my Blog "Puppet on the Edge"
http://puppet-on-the-edge.blogspot.se/
--
You received this message because you are subscribed to the Google Groups "Puppet
Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to puppet-dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/puppet-dev/ls60bk%24omb%241%40ger.gmane.org.
For more options, visit https://groups.google.com/d/optout.
