groovy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Ledbrook <pe...@cacoethes.co.uk>
Subject Re: [GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...
Date Sat, 27 Feb 2016 11:14:19 GMT
>
> 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/

Mime
View raw message