On Aug 8, 2014 5:15 PM, "Hailee Kenney" <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. 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? 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. As for names, how about 'moddoc'? 1. http://rubydoc.info/gems/yard/file/docs/GettingStarted.md 2. Gollum uses Github-flavored with some wiki-specific extensions; Jekyll by default uses either RedCarpet (1.x) or Kramdown (2.x), which have incompatible code blocks; then there's the GFMD that Github renders *.md with; we use Atlassian Stash internally, which renders some flavor, etc. -- 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/CAMmm3r7xtu%2BWZ_sN5x-OfKDGZc_%2B7veG%2B4oOL%3DmqPDdyDbXoxw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
