groovy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From MG <mg...@arscreat.com>
Subject Re: About simplifying the switch for runtime groovydoc
Date Mon, 22 Oct 2018 20:57:23 GMT
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 
> <mailto:remko.popma@gmail.com>> wrote:
>
>     MG’s arguments make sense to me.
>
>     Remko
>
>     On Oct 21, 2018, at 23:05, MG <mgbiz@arscreat.com
>     <mailto:mgbiz@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
>>>     <mailto:mgbiz@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>


Mime
View raw message