Re: About simplifying the switch for runtime groovydoc

[MG]

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 > 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

[Daniel.Sun]

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

[Remko Popma]

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  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

[Daniel.Sun]

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

[Guillaume Laforge]

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  wrote:

>
>
>
> On Oct 25, 2018, at 21:48, Keith Suderman  wrote:
>
>
>
> On Oct 24, 2018, at 8:31 PM, Remko Popma  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  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  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
> suder...@cs.vassar.edu
>
>
>
>
>

-- 
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

[Remko Popma]

> On Oct 25, 2018, at 21:48, Keith Suderman  wrote:
> 
> 
> 
>> On Oct 24, 2018, at 8:31 PM, Remko Popma  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  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  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
> suder...@cs.vassar.edu
> 
> 
> 
> 

Re: About simplifying the switch for runtime groovydoc

[Keith Suderman]

> On Oct 24, 2018, at 8:31 PM, Remko Popma  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 
> 
> 
> On Oct 24, 2018, at 23:12, Guillaume Laforge  > 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 > > 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
suder...@cs.vassar.edu






signature.asc
Description: Message signed with OpenPGP

Re: About simplifying the switch for runtime groovydoc

[Remko Popma]

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  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  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

[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  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

[Daniel.Sun]

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

[MG]

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 > wrote:


MG’s arguments make sense to me.

Remko

On Oct 21, 2018, at 23:05, MG 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 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
>    */
   

Re: About simplifying the switch for runtime groovydoc

[Remko Popma]

MG’s arguments make sense to me. 

Remko

> On Oct 21, 2018, at 23:05, MG  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  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

[Jochen Theodorou]

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

[MG]

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 > 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 mailto:sun...@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 

Re: About simplifying the switch for runtime groovydoc

[MG]

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 > 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

[Guillaume Laforge]

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  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

[MG]

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

[Daniel.Sun]

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

[Paul King]

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 
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  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 
>

Re: About simplifying the switch for runtime groovydoc

[Guillaume Laforge]

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  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