About simplifying the switch for runtime groovydoc

classic Classic list List threaded Threaded
23 messages Options
123
Reply | Threaded
Open this post in threaded view
|

About simplifying the switch for runtime groovydoc

Daniel.Sun
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
Daniel Sun
Apache Groovy committer

Blog: http://blog.sunlan.me
Twitter: @daniel_sun
Reply | Threaded
Open this post in threaded view
|

Re: About simplifying the switch for runtime groovydoc

Guillaume Laforge
Administrator
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 <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: About simplifying the switch for runtime groovydoc

Paolo Di Tommaso
Same here.

p

On Sat, Oct 20, 2018 at 8:22 PM Guillaume Laforge <[hidden email]> 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 <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: About simplifying the switch for runtime groovydoc

paulk_asert
In reply to this post by Guillaume Laforge
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 <[hidden email]> 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 <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: About simplifying the switch for runtime groovydoc

Daniel.Sun
In reply to this post by Guillaume Laforge
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
Daniel Sun
Apache Groovy committer

Blog: http://blog.sunlan.me
Twitter: @daniel_sun
MG
Reply | Threaded
Open this post in threaded view
|

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
>

Reply | Threaded
Open this post in threaded view
|

Re: About simplifying the switch for runtime groovydoc

Guillaume Laforge
Administrator
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 <[hidden email]> 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

MG
Reply | Threaded
Open this post in threaded view
|

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 <[hidden email]> 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


MG
Reply | Threaded
Open this post in threaded view
|

Re: About simplifying the switch for runtime groovydoc

MG
In reply to this post by paulk_asert
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 <[hidden email]> 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 <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: About simplifying the switch for runtime groovydoc

Jochen Theodorou
In reply to this post by paulk_asert
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

123