Re: [GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...

[Peter Ledbrook]

>
> I agree with Cédric.
> It'd be better to integrate the actual tips in the JavaDocs per se.
> Furthermore, the Groovy's GroovyDoc can also contain code samples that are
> actually tested, with assertions.
> So not only would that improve the documentation itself, without going
> through another hoop to visit a website elsewhere, but it'd also would
> increase the number of tests, ensuring higher quality, less future
> regressions, etc.
> It's really not just a matter of clicking on a link to learn more.
>

These are all good points, and yes, this is the ideal. But the danger here
is that we let the best be the enemy of the good.

Comments on this thread seem to indicate that it's trivial to extract the
relevant parts from MrHaki's blog and put them into the Javadoc directly.
It's not. It's significantly more work. Which means it's much less likely
to happen, at least on a broad front.

My suggestion is a cheap way to give users ready access to more information
on how to use various parts of Groovy. If the consensus is that the
downsides outweigh that, fair enough.

Peter
-- 
Peter Ledbrook
t: @pledbrook
w: http://www.cacoethes.co.uk/

Re: [GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...

[jim northrop]

was thinking of the same problem with our http://gpars.website. Do we
include code samples or not ? or only links to external sites ? i like the
idea of "live" code fragments within the doc.s  that are compiled/tested as
a part of document generation. this guarantees that code in our docs works
as stated. Users can then cut-n-paste with assurance.

On 27 February 2016 at 09:48, mrhaki  wrote:

> I think it is better to have very complete documentation at GroovyDoc
> level,
> without the need to follow external links.  My experience with the Ratpack
> Javadoc documentation is that with all example code and snippets included
> at
> Javadoc level that it is very easy to use as reference.
>
> It is no problem to use the snippets from my blog in the documentation.
>
> I like Guillaume's mention that the code could even be tested if it is
> included in the GroovyDoc, which makes at least sure the code works.
>
> In the nearby future I certainly want to contribute to adding snippets to
> the existing Groovydoc sources.
>
> Hubert Klein Ikkink 
> @mrhaki
> www.mrhaki.com
>
>
>
>
> --
> View this message in context:
> http://groovy.329449.n5.nabble.com/Re-GitHub-groovy-pull-request-Link-to-MrHaki-s-blog-in-TupleConstructor-jav-tp5731382p5731443.html
> Sent from the Groovy Dev mailing list archive at Nabble.com.
>