groovy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Søren Berg Glasius <soe...@glasius.dk>
Subject Re: [GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...
Date Fri, 26 Feb 2016 10:01:47 GMT
I too agree with Cédric, that they should be in the documentation. I don't know how MrHaKi's
work is licensed, but if it's open, the documentation could use his work with attributions
to him.

Best regards,
Søren Berg Glasius

Hedevej 1, Gl. Rye, 8680 Ry, Denmark
Mobile: +45 40 44 91 88, Skype: sbglasius
--- Press ESC once to quit - twice to save the changes.

From: Guillaume Laforge <glaforge@gmail.com>
Reply: dev@groovy.apache.org <dev@groovy.apache.org>
Date: February 26, 2016 at 10:53:07
To: dev@groovy.apache.org <dev@groovy.apache.org>
Subject:  Re: [GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...
 

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.

On Fri, Feb 26, 2016 at 10:49 AM, Cédric Champeau <cedric.champeau@gmail.com> wrote:
If you're ready to introduce a link to an external resource in a Javadoc, I think you should
instead make an effort to improve this particular Javadoc. I'm strongly against promoting
blogs, tutorials, ... that are by nature individual rather than community driven. That, independently
of the quality of the blog, or smartness of the author. We should think community first.

2016-02-26 9:22 GMT+01:00 Jesper Steen Møller <jesper@selskabet.org>:
Also, people these days would usually consult documentation online sources than bother with
locating any local javadoc/groovydoc documentation sources, hidden away in some local m2 repo
cache (or is that just me?). That’d make a stale link somewhat less likely, outweighed by
the goodness of Groovy Goodness. 

-Jesper

On 26. feb. 2016, at 08.35, Peter Ledbrook <peter@cacoethes.co.uk> wrote:

On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <cedric.champeau@gmail.com> wrote:
I don't think linking to external resources like this is a good idea. We don't own the end
link, it can be dead very easily, especially in the future. I would rather improve the documentation.

While I understand the concern, I think this is just one of the risks of the internet. The
docs already have links to the Java API docs, perhaps RFCs and other resources. Although you
may have more confidence in those staying where they are, they may break in future.

This is more about helping users in the short and medium term, in recognition that bulking
out the javadocs themselves isn't likely to happen at a fast pace. And I'm sure it's possible
to run checks over the generated javadocs to ensure that all links are valid. In fact, I'd
argue that should be in place already. Then we'd have some protection against any sudden unavailability
of Groovy Goodness.

Peter

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





--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Product Ninja & Advocate at Restlet

Blog: http://glaforge.appspot.com/
Social: @glaforge / Google+
Mime
View raw message