Quantcast

About a new annotation Groovydoc

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

About a new annotation Groovydoc

Daniel Sun
Hi all,

      I am going to add a new annotation Groovydoc(Retention: RUNTIME), which is configurable(e.g. -Dgroovy.attach.annotation.groovydoc=true) and can be attached to target element at compilation time automatically.

      Groovydoc can be got easily even if Groovy source code is compiled into class files, it is a bit like Python's Documentation Strings and will be useful for IDE and developers who set a high value on documentations. BTW, currently groovydoc is attached as metadata of AST node, which is only avaliable at compilation time and is a bit hard to get(we have to use CompilationUnit, which is not familiar and friendly to most of Groovy developers)

# demo for Python's Documentation Strings
def my_function():
    """Do nothing, but document it.
         No, really, it doesn't do anything.
    """
    pass
print(my_function.__doc__)  # print the Documentation Strings of the function


      Any thoughts?

Cheers,
Daniel.Sun
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: About a new annotation Groovydoc

paulk_asert
I like the idea. I thought perhaps groovy.attach.annotation.groovydoc
was a bit of a long prop name but I haven't thought of a better one
yet.

Cheers, Paul.

On Fri, Feb 24, 2017 at 12:46 PM, Daniel Sun <[hidden email]> wrote:

> Hi all,
>
>       I am going to add a new annotation Groovydoc(Retention: RUNTIME),
> which is configurable(e.g. -Dgroovy.attach.annotation.groovydoc=true) and
> can be attached to target element at compilation time automatically.
>
>       Groovydoc can be got easily even if Groovy source code is compiled
> into class files, it is a bit like Python's Documentation Strings and will
> be useful for IDE and developers who set a high value on documentations.
> BTW, currently groovydoc is attached as metadata of AST node, which is only
> avaliable at compilation time and is a bit hard to get(we have to use
> CompilationUnit, which is not familiar and friendly to most of Groovy
> developers)
>
> # demo for Python's Documentation Strings
> def my_function():
>     """Do nothing, but document it.
>          No, really, it doesn't do anything.
>     """
>     pass
> print(my_function.__doc__)  # print the Documentation Strings of the
> function
>
>
>       Any thoughts?
>
> Cheers,
> Daniel.Sun
>
>
>
> --
> View this message in context: http://groovy.329449.n5.nabble.com/About-a-new-annotation-Groovydoc-tp5738721.html
> Sent from the Groovy Dev mailing list archive at Nabble.com.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: About a new annotation Groovydoc

Guillaume Laforge
Administrator
Instead of a compilation flag... what about a special GroovyDoc annotation?

/** Foo Bar Baz @runtime-retention */
def mymethod() {}

Because otherwise it's all or nothing, not very granular.

Guillaume

On Fri, Feb 24, 2017 at 5:08 AM, Paul King <[hidden email]> wrote:
I like the idea. I thought perhaps groovy.attach.annotation.groovydoc
was a bit of a long prop name but I haven't thought of a better one
yet.

Cheers, Paul.

On Fri, Feb 24, 2017 at 12:46 PM, Daniel Sun <[hidden email]> wrote:
> Hi all,
>
>       I am going to add a new annotation Groovydoc(Retention: RUNTIME),
> which is configurable(e.g. -Dgroovy.attach.annotation.groovydoc=true) and
> can be attached to target element at compilation time automatically.
>
>       Groovydoc can be got easily even if Groovy source code is compiled
> into class files, it is a bit like Python's Documentation Strings and will
> be useful for IDE and developers who set a high value on documentations.
> BTW, currently groovydoc is attached as metadata of AST node, which is only
> avaliable at compilation time and is a bit hard to get(we have to use
> CompilationUnit, which is not familiar and friendly to most of Groovy
> developers)
>
> # demo for Python's Documentation Strings
> def my_function():
>     """Do nothing, but document it.
>          No, really, it doesn't do anything.
>     """
>     pass
> print(my_function.__doc__)  # print the Documentation Strings of the
> function
>
>
>       Any thoughts?
>
> Cheers,
> Daniel.Sun
>
>
>
> --
> View this message in context: http://groovy.329449.n5.nabble.com/About-a-new-annotation-Groovydoc-tp5738721.html
> Sent from the Groovy Dev mailing list archive at Nabble.com.



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: About a new annotation Groovydoc

jnorthr
So would dev.s need to add this annotation on EVERY method and property? Or only a single point in our groovy source?
Thx

Sent from my iPad

On 24 Feb 2017, at 07:18, Guillaume Laforge <[hidden email]> wrote:

Instead of a compilation flag... what about a special GroovyDoc annotation?

/** Foo Bar Baz @runtime-retention */
def mymethod() {}

Because otherwise it's all or nothing, not very granular.

Guillaume

On Fri, Feb 24, 2017 at 5:08 AM, Paul King <[hidden email]> wrote:
I like the idea. I thought perhaps groovy.attach.annotation.groovydoc
was a bit of a long prop name but I haven't thought of a better one
yet.

Cheers, Paul.

On Fri, Feb 24, 2017 at 12:46 PM, Daniel Sun <[hidden email]> wrote:
> Hi all,
>
>       I am going to add a new annotation Groovydoc(Retention: RUNTIME),
> which is configurable(e.g. -Dgroovy.attach.annotation.groovydoc=true) and
> can be attached to target element at compilation time automatically.
>
>       Groovydoc can be got easily even if Groovy source code is compiled
> into class files, it is a bit like Python's Documentation Strings and will
> be useful for IDE and developers who set a high value on documentations.
> BTW, currently groovydoc is attached as metadata of AST node, which is only
> avaliable at compilation time and is a bit hard to get(we have to use
> CompilationUnit, which is not familiar and friendly to most of Groovy
> developers)
>
> # demo for Python's Documentation Strings
> def my_function():
>     """Do nothing, but document it.
>          No, really, it doesn't do anything.
>     """
>     pass
> print(my_function.__doc__)  # print the Documentation Strings of the
> function
>
>
>       Any thoughts?
>
> Cheers,
> Daniel.Sun
>
>
>
> --
> View this message in context: http://groovy.329449.n5.nabble.com/About-a-new-annotation-Groovydoc-tp5738721.html
> Sent from the Groovy Dev mailing list archive at Nabble.com.



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: About a new annotation Groovydoc

Daniel Sun
In reply to this post by Guillaume Laforge
Hi  Guillaume,

> what about a special GroovyDoc annotation?
       The original purpose to add Groovydoc annotation is to store groovydoc at runtime and get groovydoc easily by accessing the annotation as usual.

        If it is GroovyDoc annotation, how can we store groovydoc and get it at runtime?  ;-)

Cheers,
Daniel.Sun
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: About a new annotation Groovydoc

Daniel Sun
In reply to this post by jnorthr
If groovydoc exists and is related to the target element, @Groovydoc will be attached to the target element(i.e. Not all target elements).

Cheers,
Daniel.Sun
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: About a new annotation Groovydoc

Remi Forax
In reply to this post by Daniel Sun
Technically,
Python was not the first language to introduce the idea of using a plain string at the start of a function as documentation, all LISPs do that :)

Rémi

----- Mail original -----
> De: "Daniel Sun" <[hidden email]>
> À: [hidden email]
> Envoyé: Vendredi 24 Février 2017 03:46:53
> Objet: About a new annotation Groovydoc

> Hi all,
>
>      I am going to add a new annotation Groovydoc(Retention: RUNTIME),
> which is configurable(e.g. -Dgroovy.attach.annotation.groovydoc=true) and
> can be attached to target element at compilation time automatically.
>
>      Groovydoc can be got easily even if Groovy source code is compiled
> into class files, it is a bit like Python's Documentation Strings and will
> be useful for IDE and developers who set a high value on documentations.
> BTW, currently groovydoc is attached as metadata of AST node, which is only
> avaliable at compilation time and is a bit hard to get(we have to use
> CompilationUnit, which is not familiar and friendly to most of Groovy
> developers)
>
> # demo for Python's Documentation Strings
> def my_function():
>    """Do nothing, but document it.
>         No, really, it doesn't do anything.
>    """
>    pass
> print(my_function.__doc__)  # print the Documentation Strings of the
> function
>
>
>      Any thoughts?
>
> Cheers,
> Daniel.Sun
>
>
>
> --
> View this message in context:
> http://groovy.329449.n5.nabble.com/About-a-new-annotation-Groovydoc-tp5738721.html
> Sent from the Groovy Dev mailing list archive at Nabble.com.
Loading...