Hi Guillaume,
thank you fro your reply. All that you are saying is evident to me since
when I perceived Groovy for the first time. It is one of the reasons I'm
so high on Groovy, and not e.g. on Kotlin (which to me has bad syntax
decisions wherever it deviates from Groovy) or Scala, etc: Groovy's
syntax has evidently been chosen and extended well over the years :-)
Apart from that: Isn't it natural that @Groovydoc has not seen much use
up to now, since it is only in Groovy 3, which does not even have a beta
release ?-)
http://docs.groovy-lang.org/docs/next/html/api/groovy/lang/Groovydoc.html
Based on the original @Groovydoc thread, where everyone seemed to agree
that it was a good feature to have:
http://groovy.329449.n5.nabble.com/About-a-new-annotation-Groovydoc-td5738721.html
http://groovy.329449.n5.nabble.com/The-new-annotation-Groovydoc-for-Groovy-3-td5739731.html
I would argue that supplying a good shortcut for its use would be a
really good idea, to entice uptake (see my previous mail).
I like Daniel's suggestion, since the @ in
/**@
reminds me of a "G", that is why this syntax has a memnonic quality to
me: It reads "Javadoc comment, Groovy style".
I also feel it could be argued that @Groovydoc is also not self
explanatory, i.e. where does that name say that the documentation will
be retained at runtime ?
Here are some alternative suggestions (If there are worries that the
syntax could be ambiguous with the added chars being meant to be part of
the comment, "**" could potentially be appended, e.g. "/**G**"):
/**$ ... "$" in a GString means "retain that object in the string"
/**G ... "Groovy doc"
/**S ... "Save comment"
/**RT ... "RunTime comment"
/**>> ... "Stream/attach comment to following construct"
/**+ ... "Add comment to following construct"
/**&& ... "Add comment to following construct"
Cheers,
mg
On 22.10.2018 10:36, Guillaume Laforge wrote:
Groovy always tried to strike a fine balance between conciseness and
readability.
If you look even at our operators, they try to convey some meaning,
like ?. is like let's try to get that field/method with the question
mark, or ?: being a contraction of the ternary operator.
But to avoid making code too cryptic, we've forbidden users to create
their own custom operators.
So let's be sure to keep the nice philosophy of the language when
discussing language changes.
I'm not fundamentally against it, but perhaps there are more readable
options.
I think @Groovydoc is rarely used (I've never seen it used in the wild
or anyone mentioning its usage or our mailing-list), so I'd tend to
prefer to see how much it's used before introducing a dedicated syntax.
Are there other notation ideas that would make the intent more
explicit? more obvious?
Guillaume
On Mon, Oct 22, 2018 at 5:00 AM Remko Popma <remko.po...@gmail.com
<mailto:remko.po...@gmail.com>> wrote:
MG’s arguments make sense to me.
Remko
On Oct 21, 2018, at 23:05, MG <mg...@arscreat.com
<mailto:mg...@arscreat.com>> wrote:
Yea, sure. But doesn't a new shorthand syntax always have that
trait ?-)
And would that not mean that we can never, ever again introduce a
shorthand notation in Groovy for anything, unless it is
syntactically based on an existing/established shorthand notation
(which in this case it kinda is, since it looks like a Javadoc
comment - with something extra. Aka Groovy ;-) ) ?
Learning a language always means learning its syntax. If you
encounter something unexpected, Google is your friend (Not a
Google expert, but I assume "/**@" should be good to find, since
it contains no spaces).
Also in this case I think it would not make a lot of difference
to the casual user: He will most likely just assume it is some
kind of Javadoc variety, if he even notices the "@" at the end.
Instead of outright blocking another proposal by Daniel, maybe we
can instead come up with a compromise that everyone can can agree
on... ?-)
Cheers,
mg
On 21.10.2018 10:51, Guillaume Laforge wrote:
Well, /** has been in use for more than 20 years, so we've had
time to get used to it.
/**@ is totally non-obvious. I've no idea what it would have
been about without having read this thread.
On Sun, Oct 21, 2018 at 4:28 AM MG <mg...@arscreat.com
<mailto:mg...@arscreat.com>> wrote:
I agree with Daniel, I think
/**@
would be neither more nor less cryptic than
/**
which everyone is just used to from Java (and which seems to
have no
memnonic / self-explanatory characteristics to me...).
Cheers,
mg
On 21.10.2018 03:04, Daniel.Sun wrote:
> Hi Guillaume,
>
> Javadoc switch `/**` is cryptic too at the
beginning, but now I
> believe few people like the following form ;-)
>
> /*
> * @Javadoc
> * some Javadoc here
> */
>
> Cheers,
> Daniel.Sun
>
>
>
>
> -----
> Daniel Sun
> Apache Groovy committer
> Blog: http://blog.sunlan.me
> Twitter: @daniel_sun
>
> --
> Sent from:
http://groovy.329449.n5.nabble.com/Groovy-Dev-f372993.html
>
--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform
Blog: http://glaforge.appspot.com/
Twitter: @glaforge <http://twitter.com/glaforge>
--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform
Blog: http://glaforge.appspot.com/
Twitter: @glaforge <http://twitter.com/glaforge>
