groovy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Konstantin Boudnik <...@apache.org>
Subject Re: [GitHub] groovy pull request: Link to MrHaki's blog in TupleConstructor jav...
Date Fri, 26 Feb 2016 15:50:47 GMT
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 <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/
> >
> >
> >

Mime
View raw message