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 <re...@hotmail.com> on 2017/02/24 02:46:53 UTC
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.
Re: About a new annotation Groovydoc
Posted by Remi Forax <fo...@univ-mlv.fr>.
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" <re...@hotmail.com>
> À: dev@groovy.incubator.apache.org
> 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.
Re: About a new annotation Groovydoc
Posted by Daniel Sun <re...@hotmail.com>.
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
--
View this message in context: http://groovy.329449.n5.nabble.com/About-a-new-annotation-Groovydoc-tp5738721p5738732.html
Sent from the Groovy Dev mailing list archive at Nabble.com.
Re: About a new annotation Groovydoc
Posted by Daniel Sun <re...@hotmail.com>.
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
--
View this message in context: http://groovy.329449.n5.nabble.com/About-a-new-annotation-Groovydoc-tp5738721p5738733.html
Sent from the Groovy Dev mailing list archive at Nabble.com.
Re: About a new annotation Groovydoc
Posted by jim northrop <ja...@googlemail.com>.
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 <gl...@gmail.com> 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 <pa...@asert.com.au> 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 <re...@hotmail.com> 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
>
> Blog: http://glaforge.appspot.com/
> Social: @glaforge / Google+
Re: About a new annotation Groovydoc
Posted by Guillaume Laforge <gl...@gmail.com>.
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 <pa...@asert.com.au> 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 <re...@hotmail.com>
> 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
Blog: http://glaforge.appspot.com/
Social: @glaforge <http://twitter.com/glaforge> / Google+
<https://plus.google.com/u/0/114130972232398734985/posts>
Re: About a new annotation Groovydoc
Posted by Paul King <pa...@asert.com.au>.
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 <re...@hotmail.com> 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.