You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@groovy.apache.org by "Daniel.Sun" <su...@apache.org> on 2018/10/20 13:28:25 UTC
About simplifying the switch for runtime groovydoc
Hi all,
Current switch for runtime groovydoc is a bit verbose, i.e.
`@Groovydoc` is a bit long. For example,
```
/**
* @Groovydoc
* some groovydoc here
*
*
```
I propose a new switch as follows(a `@` appended to `/**`):
/**@
*
* some groovydoc here
*
*
```
Any thoughts?
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
Re: About simplifying the switch for runtime groovydoc
Posted by "Daniel.Sun" <su...@apache.org>.
Hi Remko,
You can get the runtime groovydoc with reflection, here is an example:
AA.class.getMethod('m', new Class[0]).groovydoc.content.contains('method m')
BTW, I think we can add a DGM to simplify the above code ;-)
The complete example van be found at:
https://github.com/apache/groovy/blob/6da5d75c7e8fc9231a166ed40507311f30523c97/subprojects/parser-antlr4/src/test/resources/core/Groovydoc_01x.groovy
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
Re: About simplifying the switch for runtime groovydoc
Posted by Remko Popma <re...@gmail.com>.
Daniel,
Question: how do I consume the groovydoc string at runtime in the application?
For example, I would like to do something like this:
——
/**@
* Encrypts a file.
*/
class Encrypt {
static void main(String... args) {
def cli = new CliBuilder()
def descr = // how to get the groovydoc string??
cli.usageMessage.description(descr)
//...
}
}
——
> On Oct 28, 2018, at 19:45, Daniel.Sun <su...@apache.org> wrote:
>
> Hi Guillaume,
>
>> it's still possible to change the syntax at this time without any harm.
>
> Here is the PR to complete the change:
> https://github.com/apache/groovy/pull/817
>
> 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
Re: About simplifying the switch for runtime groovydoc
Posted by "Daniel.Sun" <su...@apache.org>.
Hi Guillaume,
> it's still possible to change the syntax at this time without any harm.
Here is the PR to complete the change:
https://github.com/apache/groovy/pull/817
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
Re: About simplifying the switch for runtime groovydoc
Posted by Guillaume Laforge <gl...@gmail.com>.
Since it's for Groovy 3.0, and @GroovyDoc hasn't yet been available in an
officially released version, it's still possible to change the syntax at
this time without any harm.
On Sun, Oct 28, 2018 at 7:40 AM Remko Popma <re...@gmail.com> wrote:
>
>
>
> On Oct 25, 2018, at 21:48, Keith Suderman <su...@cs.vassar.edu> wrote:
>
>
>
> On Oct 24, 2018, at 8:31 PM, Remko Popma <re...@gmail.com> wrote:
>
> In addition, there is nothing about the long @GroovyDoc notation that
> tells me the doc string is retained at runtime. So it isn’t actually
> clearer...
>
>
> This. When I first saw @GroovyDoc my initial reaction was, "Of course it
> is GroovyDoc, it is a .groovy file, what else would it be?". I had to
> Google to find the original thread to discover that it was "Runtime
> GroovyDoc". So I think something like @Runtime would be much clearer and
> informative than @GroovyDoc.
>
> But having said that, I have never said to myself, "I wish I could make
> this GroovyDoc available at runtime." So I would wait to see how the
> annotation is used in the wild before considering shortcuts.
>
>
> I see runtime GroovyDoc to be useful in the next generation of CliBuilder,
> where users could write runtime GroovyDoc documentation that would become
> part of the usage help message of the command line utility.
>
> Allowing users to accomplish this with a /**@ notation seems a lot more
> elegant and Groovier than something relatively heavy-looking like @GroovyDoc
> or the more explicit @RuntimeGroovyDoc.
>
> So let me ask again, do we even need a long notation? Is it possible to
> make the /**@ the public API for this feature _instead of_ @GroovyDoc or
> @RuntimeGroovyDoc?
>
> Remko.
>
>
> My two cents,
> Keith
>
>
> Remko.
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
> On Oct 24, 2018, at 23:12, Guillaume Laforge <gl...@gmail.com> wrote:
>
> Not necessarily. Discussions are better, leading towards a consensus.
> Polls can have very different outcomes depending on how you define the
> questions and answers, how you advertise the poll, how you interpret the
> results of the poll, etc.
> Before any poll, I'd like to hear about those early users of this
> non-released-yet feature, to hear what their thoughts are.
> There's no need to hurry or rush towards adding this shortcut notation.
>
>
> On Wed, Oct 24, 2018 at 3:57 PM Daniel.Sun <su...@apache.org> wrote:
>
>> Raising a poll may be better way to make decisions ;)
>>
>> 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>
>
>
> ----------------------
> Keith Suderman
> Research Associate
> Department of Computer Science
> Vassar College, Poughkeepsie NY
> suderman@cs.vassar.edu
>
>
>
>
>
--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform
Blog: http://glaforge.appspot.com/
Twitter: @glaforge <http://twitter.com/glaforge>
Re: About simplifying the switch for runtime groovydoc
Posted by Remko Popma <re...@gmail.com>.
> On Oct 25, 2018, at 21:48, Keith Suderman <su...@cs.vassar.edu> wrote:
>
>
>
>> On Oct 24, 2018, at 8:31 PM, Remko Popma <re...@gmail.com> wrote:
>>
>> In addition, there is nothing about the long @GroovyDoc notation that tells me the doc string is retained at runtime. So it isn’t actually clearer...
>
> This. When I first saw @GroovyDoc my initial reaction was, "Of course it is GroovyDoc, it is a .groovy file, what else would it be?". I had to Google to find the original thread to discover that it was "Runtime GroovyDoc". So I think something like @Runtime would be much clearer and informative than @GroovyDoc.
>
> But having said that, I have never said to myself, "I wish I could make this GroovyDoc available at runtime." So I would wait to see how the annotation is used in the wild before considering shortcuts.
I see runtime GroovyDoc to be useful in the next generation of CliBuilder, where users could write runtime GroovyDoc documentation that would become part of the usage help message of the command line utility.
Allowing users to accomplish this with a /**@ notation seems a lot more elegant and Groovier than something relatively heavy-looking like @GroovyDoc or the more explicit @RuntimeGroovyDoc.
So let me ask again, do we even need a long notation? Is it possible to make the /**@ the public API for this feature _instead of_ @GroovyDoc or @RuntimeGroovyDoc?
Remko.
>
> My two cents,
> Keith
>
>>
>> Remko.
>>
>> (Shameless plug) Every java main() method deserves http://picocli.info
>>
>>> On Oct 24, 2018, at 23:12, Guillaume Laforge <gl...@gmail.com> wrote:
>>>
>>> Not necessarily. Discussions are better, leading towards a consensus.
>>> Polls can have very different outcomes depending on how you define the questions and answers, how you advertise the poll, how you interpret the results of the poll, etc.
>>> Before any poll, I'd like to hear about those early users of this non-released-yet feature, to hear what their thoughts are.
>>> There's no need to hurry or rush towards adding this shortcut notation.
>>>
>>>
>>>> On Wed, Oct 24, 2018 at 3:57 PM Daniel.Sun <su...@apache.org> wrote:
>>>> Raising a poll may be better way to make decisions ;)
>>>>
>>>> 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
>
> ----------------------
> Keith Suderman
> Research Associate
> Department of Computer Science
> Vassar College, Poughkeepsie NY
> suderman@cs.vassar.edu
>
>
>
>
Re: About simplifying the switch for runtime groovydoc
Posted by Keith Suderman <su...@cs.vassar.edu>.
> On Oct 24, 2018, at 8:31 PM, Remko Popma <re...@gmail.com> wrote:
>
> In addition, there is nothing about the long @GroovyDoc notation that tells me the doc string is retained at runtime. So it isn’t actually clearer...
This. When I first saw @GroovyDoc my initial reaction was, "Of course it is GroovyDoc, it is a .groovy file, what else would it be?". I had to Google to find the original thread to discover that it was "Runtime GroovyDoc". So I think something like @Runtime would be much clearer and informative than @GroovyDoc.
But having said that, I have never said to myself, "I wish I could make this GroovyDoc available at runtime." So I would wait to see how the annotation is used in the wild before considering shortcuts.
My two cents,
Keith
>
> Remko.
>
> (Shameless plug) Every java main() method deserves http://picocli.info <http://picocli.info/>
>
> On Oct 24, 2018, at 23:12, Guillaume Laforge <glaforge@gmail.com <ma...@gmail.com>> wrote:
>
>> Not necessarily. Discussions are better, leading towards a consensus.
>> Polls can have very different outcomes depending on how you define the questions and answers, how you advertise the poll, how you interpret the results of the poll, etc.
>> Before any poll, I'd like to hear about those early users of this non-released-yet feature, to hear what their thoughts are.
>> There's no need to hurry or rush towards adding this shortcut notation.
>>
>>
>> On Wed, Oct 24, 2018 at 3:57 PM Daniel.Sun <sunlan@apache.org <ma...@apache.org>> wrote:
>> Raising a poll may be better way to make decisions ;)
>>
>> Cheers,
>> Daniel.Sun
>>
>>
>>
>>
>> -----
>> Daniel Sun
>> Apache Groovy committer
>> Blog: http://blog.sunlan.me <http://blog.sunlan.me/>
>> Twitter: @daniel_sun
>>
>> --
>> Sent from: http://groovy.329449.n5.nabble.com/Groovy-Dev-f372993.html <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/ <http://glaforge.appspot.com/>
>> Twitter: @glaforge <http://twitter.com/glaforge>
----------------------
Keith Suderman
Research Associate
Department of Computer Science
Vassar College, Poughkeepsie NY
suderman@cs.vassar.edu
Re: About simplifying the switch for runtime groovydoc
Posted by Remko Popma <re...@gmail.com>.
I like the short notation much better than the long notation.
The /** notation for Javadoc was cryptic 20 years ago but there was no resistance to the idea. Why not? Because it was such a useful feature of the language!
I think we all agree that making GroovyDoc available at runtime is a useful feature. Why do we even need a @GroovyDoc tag?
The /**@ notation makes runtime GroovyDoc a first-class citizen of the language. This seems much better than requiring an overly verbose @GroovyDoc tag.
In addition, there is nothing about the long @GroovyDoc notation that tells me the doc string is retained at runtime. So it isn’t actually clearer...
Remko.
(Shameless plug) Every java main() method deserves http://picocli.info
> On Oct 24, 2018, at 23:12, Guillaume Laforge <gl...@gmail.com> wrote:
>
> Not necessarily. Discussions are better, leading towards a consensus.
> Polls can have very different outcomes depending on how you define the questions and answers, how you advertise the poll, how you interpret the results of the poll, etc.
> Before any poll, I'd like to hear about those early users of this non-released-yet feature, to hear what their thoughts are.
> There's no need to hurry or rush towards adding this shortcut notation.
>
>
>> On Wed, Oct 24, 2018 at 3:57 PM Daniel.Sun <su...@apache.org> wrote:
>> Raising a poll may be better way to make decisions ;)
>>
>> 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
Re: About simplifying the switch for runtime groovydoc
Posted by MG <mg...@arscreat.com>.
Agree with Guillaume here: In my (bad) experience, 15 Facebook friends
is all it takes to swing nearly any poll in your favour and get a
landslide victory.
Am 24.10.2018 um 16:12 schrieb Guillaume Laforge:
> Not necessarily. Discussions are better, leading towards a consensus.
> Polls can have very different outcomes depending on how you define the
> questions and answers, how you advertise the poll, how you interpret
> the results of the poll, etc.
> Before any poll, I'd like to hear about those early users of this
> non-released-yet feature, to hear what their thoughts are.
> There's no need to hurry or rush towards adding this shortcut notation.
>
>
> On Wed, Oct 24, 2018 at 3:57 PM Daniel.Sun <sunlan@apache.org
> <ma...@apache.org>> wrote:
>
> Raising a poll may be better way to make decisions ;)
>
> 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>
Re: About simplifying the switch for runtime groovydoc
Posted by Guillaume Laforge <gl...@gmail.com>.
Not necessarily. Discussions are better, leading towards a consensus.
Polls can have very different outcomes depending on how you define the
questions and answers, how you advertise the poll, how you interpret the
results of the poll, etc.
Before any poll, I'd like to hear about those early users of this
non-released-yet feature, to hear what their thoughts are.
There's no need to hurry or rush towards adding this shortcut notation.
On Wed, Oct 24, 2018 at 3:57 PM Daniel.Sun <su...@apache.org> wrote:
> Raising a poll may be better way to make decisions ;)
>
> 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>
Re: About simplifying the switch for runtime groovydoc
Posted by "Daniel.Sun" <su...@apache.org>.
Raising a poll may be better way to make decisions ;)
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
Re: About simplifying the switch for runtime groovydoc
Posted by MG <mg...@arscreat.com>.
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.popma@gmail.com
> <ma...@gmail.com>> wrote:
>
> MG’s arguments make sense to me.
>
> Remko
>
> On Oct 21, 2018, at 23:05, MG <mgbiz@arscreat.com
> <ma...@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 <mgbiz@arscreat.com
>>> <ma...@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>
Re: About simplifying the switch for runtime groovydoc
Posted by Guillaume Laforge <gl...@gmail.com>.
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 <re...@gmail.com> wrote:
> MG’s arguments make sense to me.
>
> Remko
>
> On Oct 21, 2018, at 23:05, MG <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> 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>
Re: About simplifying the switch for runtime groovydoc
Posted by Remko Popma <re...@gmail.com>.
MG’s arguments make sense to me.
Remko
> On Oct 21, 2018, at 23:05, MG <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> 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
>
Re: About simplifying the switch for runtime groovydoc
Posted by MG <mg...@arscreat.com>.
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 <mgbiz@arscreat.com
> <ma...@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>
Re: About simplifying the switch for runtime groovydoc
Posted by Guillaume Laforge <gl...@gmail.com>.
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> 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>
Re: About simplifying the switch for runtime groovydoc
Posted by MG <mg...@arscreat.com>.
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
>
Re: About simplifying the switch for runtime groovydoc
Posted by "Daniel.Sun" <su...@apache.org>.
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
Re: About simplifying the switch for runtime groovydoc
Posted by MG <mg...@arscreat.com>.
Here is the problem I see with this approach (which I have seen multiple
times now since I joined the ML):
1. The (oftentimes imho plausible) argument for introducing something
new in Groovy is, that current support is too cumbersome (as with
Daniel's proposal).
2. The suggestion then is, to stick with the current variety, and see
how much uptake it gets in the community.
3. But evidently there is a contradictio in se here: If one agrees that
current support in Groovy is too cumbersome, uptake will naturally
not be high, which is then taken to imply that Groovy users don't
want that feature at all (hence there is no need to make its use
less cumbersome). Case closed.
So I feel one should either state that one does not agree with the
assumption of usability of a feature being bad, or bring another
argument. Otherwise over time it feels just like a polemic trick to "let
people down easy"...
I understand that introducing new syntax or features to a language has
to be carefully considered, as to not back oneself into a corner etc.
But this proposal looks quite harmless to me, as well as being
syntactically sound. Which I might be mistaken about, of course - but
then one sentence should suffice to point out problematic areas :-)
Cheers,
mg
On 21.10.2018 00:42, Paul King wrote:
> I am not against a shortened form but I'd wait and see how usage
> of @Groovydoc goes first.
> If it's use is extremely popular it would make sense to consider
> shortcuts.
>
> On Sun, Oct 21, 2018 at 4:22 AM Guillaume Laforge <glaforge@gmail.com
> <ma...@gmail.com>> wrote:
>
> I find that a bit too cryptic.
> I prefer it to be more explicit, even if a bit more verbose.
>
> On Sat, Oct 20, 2018 at 3:28 PM Daniel.Sun <sunlan@apache.org
> <ma...@apache.org>> wrote:
>
> Hi all,
>
> Current switch for runtime groovydoc is a bit verbose,
> i.e.
> `@Groovydoc` is a bit long. For example,
> ```
> /**
> * @Groovydoc
> * some groovydoc here
> *
> *
>
> ```
>
> I propose a new switch as follows(a `@` appended to
> `/**`):
>
> /**@
> *
> * some groovydoc here
> *
> *
>
> ```
>
> Any thoughts?
>
> 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>
>
Re: About simplifying the switch for runtime groovydoc
Posted by Jochen Theodorou <bl...@gmx.org>.
On 21.10.2018 00:42, Paul King wrote:
> I am not against a shortened form but I'd wait and see how usage
> of @Groovydoc goes first.
> If it's use is extremely popular it would make sense to consider shortcuts.
agreed... on a side topic... do we have to do something with Groovydoc
for later java versions? Javadoc changed. It changed in 9 because of
modules and I think they decided to remove overview... frames is a no go
for long already
bye Jochen
Re: About simplifying the switch for runtime groovydoc
Posted by Paul King <pa...@asert.com.au>.
I am not against a shortened form but I'd wait and see how usage
of @Groovydoc goes first.
If it's use is extremely popular it would make sense to consider shortcuts.
On Sun, Oct 21, 2018 at 4:22 AM Guillaume Laforge <gl...@gmail.com>
wrote:
> I find that a bit too cryptic.
> I prefer it to be more explicit, even if a bit more verbose.
>
> On Sat, Oct 20, 2018 at 3:28 PM Daniel.Sun <su...@apache.org> wrote:
>
>> Hi all,
>>
>> Current switch for runtime groovydoc is a bit verbose, i.e.
>> `@Groovydoc` is a bit long. For example,
>> ```
>> /**
>> * @Groovydoc
>> * some groovydoc here
>> *
>> *
>>
>> ```
>>
>> I propose a new switch as follows(a `@` appended to `/**`):
>>
>> /**@
>> *
>> * some groovydoc here
>> *
>> *
>>
>> ```
>>
>> Any thoughts?
>>
>> 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>
>
Re: About simplifying the switch for runtime groovydoc
Posted by Paolo Di Tommaso <pa...@gmail.com>.
Same here.
p
On Sat, Oct 20, 2018 at 8:22 PM Guillaume Laforge <gl...@gmail.com>
wrote:
> I find that a bit too cryptic.
> I prefer it to be more explicit, even if a bit more verbose.
>
> On Sat, Oct 20, 2018 at 3:28 PM Daniel.Sun <su...@apache.org> wrote:
>
>> Hi all,
>>
>> Current switch for runtime groovydoc is a bit verbose, i.e.
>> `@Groovydoc` is a bit long. For example,
>> ```
>> /**
>> * @Groovydoc
>> * some groovydoc here
>> *
>> *
>>
>> ```
>>
>> I propose a new switch as follows(a `@` appended to `/**`):
>>
>> /**@
>> *
>> * some groovydoc here
>> *
>> *
>>
>> ```
>>
>> Any thoughts?
>>
>> 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>
>
Re: About simplifying the switch for runtime groovydoc
Posted by Guillaume Laforge <gl...@gmail.com>.
I find that a bit too cryptic.
I prefer it to be more explicit, even if a bit more verbose.
On Sat, Oct 20, 2018 at 3:28 PM Daniel.Sun <su...@apache.org> wrote:
> Hi all,
>
> Current switch for runtime groovydoc is a bit verbose, i.e.
> `@Groovydoc` is a bit long. For example,
> ```
> /**
> * @Groovydoc
> * some groovydoc here
> *
> *
>
> ```
>
> I propose a new switch as follows(a `@` appended to `/**`):
>
> /**@
> *
> * some groovydoc here
> *
> *
>
> ```
>
> Any thoughts?
>
> 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>