You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@groovy.apache.org by pledbrook <gi...@git.apache.org> on 2016/02/24 17:25:55 UTC
[GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...
GitHub user pledbrook opened a pull request:
https://github.com/apache/groovy/pull/271
Link to MrHaki's blog in TupleConstructor javadoc.
As discussed on Twitter, here's an example of linking to @mrhaki's blog from the javadocs so that people have ready access to more examples for certain classes. If this gets merged, I'll look into adding more.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/pledbrook/incubator-groovy patch-01
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/groovy/pull/271.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #271
----
commit 6741ce458c01cf8ab5df770a284d53a3657dd389
Author: Peter Ledbrook <pe...@cacoethes.co.uk>
Date: 2016-02-24T16:23:07Z
Link to MrHaki's blog in TupleConstructor javadoc.
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
Re: [GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...
Posted by Suderman Keith <ke...@vassar.edu>.
I side with Cédric here. The Java/Groovy docs should only link to other parts of the official documentation, or at least to endpoints the Groovy team controls. I don’t have to go online to read the docs or root around in my ~/.m2 repo to find them, they are displayed automagically by my IDE and should never contain broken links.
I strongly suspect that if someone on the Groovy team were to reach out to Mr Haki (Hubert) that he would allow snippets of his blog posts to be included in the official documentation.
> On Feb 26, 2016, at 3:22 AM, Jesper Steen Møller <je...@selskabet.org> wrote:
>
> 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 <ma...@cacoethes.co.uk>> wrote:
>>
>> On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <cedric.champeau@gmail.com <ma...@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/ <http://www.cacoethes.co.uk/>
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Paco Zarate <co...@nazcasistemas.com>.
Is it possible to include blog links or samples as:
"External References:"
?
I think that someone that wants to help with the documentation can have a
very good starting point with the external references on hand, and it is
very clear that is not the "Official documentation"
On Mon, Feb 29, 2016 at 10:43 AM, Konstantin Boudnik <co...@apache.org> wrote:
> On Mon, Feb 29, 2016 at 06:40PM, Cédric Champeau wrote:
> > 2016-02-29 18:37 GMT+01:00 Konstantin Boudnik <co...@apache.org>:
> >
> > > Sorry for a delay in the answer...
> > >
> > > On Mon, Feb 29, 2016 at 12:01PM, Jochen Theodorou wrote:
> > > >
> > > > On 27.02.2016 05:26, Aseem Bansal wrote:
> > > > >Hi Konstantin Boudnik
> > > > >
> > > > >Are the things on groovy-lang not considered originating from Apache
> > > > >premises?
> > >
> > > Where the code for groovy-lang is hosted? That will answer your
> question.
> > >
> >
> > The website itself is in its own Git repo. However, the docs that it
> > contains are hosted into the main Apache Groovy Git repo.
>
> Then it seems to be originating from the Apache, as far as I can tell.
>
> > > > If we link to Mr Hakis blog, and that is seen as Docs, then we have
> > > > external Docs, which do not originate from the ASF. In my opinion no
> > > > problem, since these are blog posts and not docs. Especially not
> > > > since his blog is about more than Groovy alone
> > >
> > > That could be fine if the link is explicitly external and not included
> into
> > > the release _materially_, ie the content isn't copied into the release
> zip,
> > > etc. Because then will have to figure out about the status of this
> > > contribution, licensing, and all that jazz.
> > >
> > > Cos
> > >
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Konstantin Boudnik <co...@apache.org>.
On Mon, Feb 29, 2016 at 06:40PM, Cédric Champeau wrote:
> 2016-02-29 18:37 GMT+01:00 Konstantin Boudnik <co...@apache.org>:
>
> > Sorry for a delay in the answer...
> >
> > On Mon, Feb 29, 2016 at 12:01PM, Jochen Theodorou wrote:
> > >
> > > On 27.02.2016 05:26, Aseem Bansal wrote:
> > > >Hi Konstantin Boudnik
> > > >
> > > >Are the things on groovy-lang not considered originating from Apache
> > > >premises?
> >
> > Where the code for groovy-lang is hosted? That will answer your question.
> >
>
> The website itself is in its own Git repo. However, the docs that it
> contains are hosted into the main Apache Groovy Git repo.
Then it seems to be originating from the Apache, as far as I can tell.
> > > If we link to Mr Hakis blog, and that is seen as Docs, then we have
> > > external Docs, which do not originate from the ASF. In my opinion no
> > > problem, since these are blog posts and not docs. Especially not
> > > since his blog is about more than Groovy alone
> >
> > That could be fine if the link is explicitly external and not included into
> > the release _materially_, ie the content isn't copied into the release zip,
> > etc. Because then will have to figure out about the status of this
> > contribution, licensing, and all that jazz.
> >
> > Cos
> >
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Cédric Champeau <ce...@gmail.com>.
2016-02-29 18:37 GMT+01:00 Konstantin Boudnik <co...@apache.org>:
> Sorry for a delay in the answer...
>
> On Mon, Feb 29, 2016 at 12:01PM, Jochen Theodorou wrote:
> >
> > On 27.02.2016 05:26, Aseem Bansal wrote:
> > >Hi Konstantin Boudnik
> > >
> > >Are the things on groovy-lang not considered originating from Apache
> > >premises?
>
> Where the code for groovy-lang is hosted? That will answer your question.
>
The website itself is in its own Git repo. However, the docs that it
contains are hosted into the main Apache Groovy Git repo.
>
> > If we link to Mr Hakis blog, and that is seen as Docs, then we have
> > external Docs, which do not originate from the ASF. In my opinion no
> > problem, since these are blog posts and not docs. Especially not
> > since his blog is about more than Groovy alone
>
> That could be fine if the link is explicitly external and not included into
> the release _materially_, ie the content isn't copied into the release zip,
> etc. Because then will have to figure out about the status of this
> contribution, licensing, and all that jazz.
>
> Cos
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Konstantin Boudnik <co...@apache.org>.
Sorry for a delay in the answer...
On Mon, Feb 29, 2016 at 12:01PM, Jochen Theodorou wrote:
>
> On 27.02.2016 05:26, Aseem Bansal wrote:
> >Hi Konstantin Boudnik
> >
> >Are the things on groovy-lang not considered originating from Apache
> >premises?
Where the code for groovy-lang is hosted? That will answer your question.
> If we link to Mr Hakis blog, and that is seen as Docs, then we have
> external Docs, which do not originate from the ASF. In my opinion no
> problem, since these are blog posts and not docs. Especially not
> since his blog is about more than Groovy alone
That could be fine if the link is explicitly external and not included into
the release _materially_, ie the content isn't copied into the release zip,
etc. Because then will have to figure out about the status of this
contribution, licensing, and all that jazz.
Cos
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Jochen Theodorou <bl...@gmx.org>.
On 27.02.2016 05:26, Aseem Bansal wrote:
> Hi Konstantin Boudnik
>
> Are the things on groovy-lang not considered originating from Apache
> premises?
If we link to Mr Hakis blog, and that is seen as Docs, then we have
external Docs, which do not originate from the ASF. In my opinion no
problem, since these are blog posts and not docs. Especially not since
his blog is about more than Groovy alone
bye Jochen
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Aseem Bansal <as...@gmail.com>.
Hi Konstantin Boudnik
Are the things on groovy-lang not considered originating from Apache
premises? The repository for the same is licensed to Apache and is in
Apache's git repository. Am I missing something here?
On Fri, Feb 26, 2016 at 9:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
> There's another concern: docs of an Apache project has to originate, as the
> source code, from Apache premises (Infra, etc.) While linking doesn't
> exactly
> violates this, it is still looks like "Ok, here's our documentation, but
> for
> this little piece you'd need to go and check somewhere else". There's also
> potential licensing and IP clearance issues.
>
> If Groovy needs this piece of docs the best way would be to reach out to
> MrHaki and persuade him to contribute the content to the Javadocs we
> already
> have.
>
> Cos
>
> On Fri, Feb 26, 2016 at 10:49AM, Cédric Champeau 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 <je...@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 <pe...@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/
> > >
> > >
> > >
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Konstantin Boudnik <co...@apache.org>.
There's another concern: docs of an Apache project has to originate, as the
source code, from Apache premises (Infra, etc.) While linking doesn't exactly
violates this, it is still looks like "Ok, here's our documentation, but for
this little piece you'd need to go and check somewhere else". There's also
potential licensing and IP clearance issues.
If Groovy needs this piece of docs the best way would be to reach out to
MrHaki and persuade him to contribute the content to the Javadocs we already
have.
Cos
On Fri, Feb 26, 2016 at 10:49AM, Cédric Champeau 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 <je...@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 <pe...@cacoethes.co.uk> wrote:
> >
> > On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <ce...@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/
> >
> >
> >
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by jim northrop <ja...@googlemail.com>.
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 <h....@gmail.com> 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>
> @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.
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by mrhaki <h....@gmail.com>.
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>
@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.
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Aseem Bansal <as...@gmail.com>.
Hi
Rather than linking to Mr. Haki or improving this particular Java why not
link to http://groovy-lang.org/metaprogramming.html#xform-TupleConstructor?
IMO that is better than either of the 2 suggestions. The meta programming
doc is community driven and already present.
On Fri, Feb 26, 2016 at 3:31 PM, Søren Berg Glasius <so...@glasius.dk>
wrote:
> 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 <gl...@gmail.com> <gl...@gmail.com>
> Reply: dev@groovy.apache.org <de...@groovy.apache.org>
> <de...@groovy.apache.org>
> Date: February 26, 2016 at 10:53:07
> To: dev@groovy.apache.org <de...@groovy.apache.org> <de...@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 <je...@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 <pe...@cacoethes.co.uk>
>>> wrote:
>>>
>>> On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <ce...@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 <http://restlet.com>
>
> Blog: http://glaforge.appspot.com/
> Social: @glaforge <http://twitter.com/glaforge> / Google+
> <https://plus.google.com/u/0/114130972232398734985/posts>
>
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Søren Berg Glasius <so...@glasius.dk>.
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 <gl...@gmail.com>
Reply: dev@groovy.apache.org <de...@groovy.apache.org>
Date: February 26, 2016 at 10:53:07
To: dev@groovy.apache.org <de...@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 <ce...@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 <je...@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 <pe...@cacoethes.co.uk> wrote:
On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <ce...@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+
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Peter Ledbrook <pe...@cacoethes.co.uk>.
>
> 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...
Posted by Guillaume Laforge <gl...@gmail.com>.
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 <je...@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 <pe...@cacoethes.co.uk> wrote:
>>
>> On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <ce...@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 <http://restlet.com>
Blog: http://glaforge.appspot.com/
Social: @glaforge <http://twitter.com/glaforge> / Google+
<https://plus.google.com/u/0/114130972232398734985/posts>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Cédric Champeau <ce...@gmail.com>.
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 <je...@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 <pe...@cacoethes.co.uk> wrote:
>
> On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <ce...@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/
>
>
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Pascal Schumacher <pa...@gmx.net>.
Well it's not really hidden, as the groovy/javadoc is published on the
web and quite high in the google search results (at least for me).
Also you can configure e.g. Eclipse to automatically download sources
and javadocs for all dependencies, so it's directly visible in the IDE.
Cheers,
Pascal
Am 26.02.2016 um 09:22 schrieb Jesper Steen Møller:
> 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
>> <ma...@cacoethes.co.uk>> wrote:
>>
>> On Wed, 24 Feb 2016 at 16:30 Cédric Champeau
>> <cedric.champeau@gmail.com <ma...@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/
>
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Peter Ledbrook <pe...@cacoethes.co.uk>.
On Wed, 24 Feb 2016 at 16:30 Cédric Champeau <ce...@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/
Re: [GitHub] groovy pull request: Link to MrHaki's blog in
TupleConstructor jav...
Posted by Cédric Champeau <ce...@gmail.com>.
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.
2016-02-24 17:25 GMT+01:00 pledbrook <gi...@git.apache.org>:
> GitHub user pledbrook opened a pull request:
>
> https://github.com/apache/groovy/pull/271
>
> Link to MrHaki's blog in TupleConstructor javadoc.
>
> As discussed on Twitter, here's an example of linking to @mrhaki's
> blog from the javadocs so that people have ready access to more examples
> for certain classes. If this gets merged, I'll look into adding more.
>
> You can merge this pull request into a Git repository by running:
>
> $ git pull https://github.com/pledbrook/incubator-groovy patch-01
>
> Alternatively you can review and apply these changes as the patch at:
>
> https://github.com/apache/groovy/pull/271.patch
>
> To close this pull request, make a commit to your master/trunk branch
> with (at least) the following in the commit message:
>
> This closes #271
>
> ----
> commit 6741ce458c01cf8ab5df770a284d53a3657dd389
> Author: Peter Ledbrook <pe...@cacoethes.co.uk>
> Date: 2016-02-24T16:23:07Z
>
> Link to MrHaki's blog in TupleConstructor javadoc.
>
> ----
>
>
> ---
> If your project is set up for it, you can reply to this email and have your
> reply appear on GitHub as well. If your project does not have this feature
> enabled and wishes so, or if the feature is enabled but not working, please
> contact infrastructure at infrastructure@apache.org or file a JIRA ticket
> with INFRA.
> ---
>
[GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/groovy/pull/271
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---