On Sat, Aug 9, 2014 at 1:29 PM, Henrik Lindberg < [email protected]> wrote:
> On 2014-09-08 20:32, Wil Cooley wrote: > >> On Aug 8, 2014 5:15 PM, "Hailee Kenney" <[email protected] >> <mailto:[email protected]>> 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 [email protected]. > 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. > Thanks for all the feedback everyone! Going back to the issue of naming, I have a list of suggestions I've collected that I wanted throw out there for discussion: puppet strings (this seems to be a popular choice) puppet readme puppet guide puppet usage puppet dox puppet watson (or potentially another muppet-related name) puppet pub / puppet pubs (as in publication) puppet tome puppet info puppet eyes Thoughts on any of these? -- Hailee Kenney [email protected] Associate Developer, Puppet Labs *Join us at PuppetConf 2014 <http://www.puppetconf.com/>, September 20-24 in San Francisco* *Register by September 8th to take advantage of the Final Countdown <https://www.eventbrite.com/e/puppetconf-2014-tickets-7666774529?discount=FinalCountdown> * *—**save $149!* -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/CALdYGa8yKMpf8K1p-RgbY18paQv1rooc%3DNFBW1_X-0NddMUaRQ%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
