On Sat, Aug 9, 2014 at 1:29 PM, Henrik Lindberg < henrik.lindb...@cloudsmith.com> wrote:
> 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. > 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 hai...@puppetlabs.com 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 puppet-dev+unsubscr...@googlegroups.com. 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.
