>Runtime retention is a potential problem, as an extra binary may be needed.
>The jar might no longer be a drop-in replacement.
That is exactly while the annotations are an option only to use.
On Wed, Aug 28, 2019 at 4:17 PM sebb <seb...@gmail.com> wrote:
> On Wed, 28 Aug 2019 at 14:55, Peter Verhas <pe...@verhas.com> wrote:
> >
> > Bruno P. Kinoshita>But if you could perhaps show the pros and cons,
> >
> > There is a slight overhead marking and naming the code snippets and also
> > the code segments where the snippets should be inserted. It is slightly
> > more complex than just copy-paste but not a big deal. If the unit test
> > lines are not used verbatim as they are then the lines can also be
> > converted using replaceAll style regular expressions. To create these may
> > also be more a kind of programming work than just reformatting the
> > copy-pasted code manually.
> >
> > On the other hand when the lines in the snippet change they will update
> the
> > JavaDoc automatically. This is the main advantage.
> >
> > >what is the maintenance involved
> >
> > The copy-paste (code generation) is started from the test. If there is
> any
> > change the test signals it with failure. This may seem strange that in
> that
> > case, the test has to be executed again and then it runs fine. This is to
> > ensure that the generated code is compiled properly. The final code:
> manual
> > modification + generated modification should be committed and that way
> the
> > test never generates anything new on the CI server and thus it does not
> > fail. That way this is a "manual" tool.
> >
> > >whether it would change anything in the final binary that the user sees
> or
> > not,
> >
> > The tool was designed to have zero footprints on the final binary. There
> is
> > no run-time dependency, especially when using it for documentation
> > generation. The binary will exactly be the same.
> >
> > When it is used to generate Java code the developer MAY decide to use
> some
> > annotations, but it is not a must. It is a convenience feature. Since
> these
> > annotations have run-time retention they are compiled dependencies, but
> > again: it is not a must and all features are available without these. The
> > framework works scanning annotation like comments a.k.a.:
>
> Runtime retention is a potential problem, as an extra binary may be needed.
> The jar might no longer be a drop-in replacement.
>
> > //@Geci(" .... ")
> >
> > or just any annotation so long as long the simple name of the annotation
> is
> > "Geci" or the annotation itself is annotated with an annotation that has
> a
> > simple name "Geci" (recursively). The generators may even trigger on
> > //<editor-fold ...> comments, no need for annotations. And it is for Java
> > code generation. The document generation is totally zero footprint.
> >
> >
> > Silence Tai
> > >I am more concerned about what changes the project will need to make
> after
> > relying on the tool.
> >
> > It is a test dependency. Ignited using unit tests. Writes into the source
> > code. To get rid: remove the dependency and delete the tests. All
> generated
> > code is part of the source. No hard-to-get-rid-off dependency. Except if
> > you start to write code generators as plugins, then this type of
> > metaprogramming is addictive. But that is not a technical issue, more
> > psychology.
> >
> >
> > Paul King
> >
> >
> >
> >
> >
> >
> > >You can stop using the JavadocAssertionTestSuite at any time.
> > >The code will still be in the Javadoc as documentation but just won't
> > >be tested any more as part of your test suite.
> >
> > This is the same for Java::Geci. The difference is that Java::Geci works
> > the other way around. It fetches code from the unit test (or for that
> > matter from just any text file which contains snippets) and puts it into
> > the JavaDoc (or for that matter into any text file that contains a
> > segment). In this sense Java::Geci is more general, not a unit test
> > specific tool. It is a tool to copy -- alter -- paste text snippets
> between
> > files.
> >
> > Gary Gregory
> >
> > I had a brief look at lemma. It is similar to what I used to write my
> book
> > Java Projects - Secon Edition with PACKT. That tool is Python and named
> > pyama. Actually the first such tool I wrote in 2006 using Perl. I feel
> that
> > Java::Geci is a bit more flexible than that. I am not sure about that
> > though.
> >
> >
> > I think that the next step is that I will create a short sample with a
> pull
> > request.
> >
> > Peter
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> > On Wed, Aug 28, 2019 at 10:12 AM Paul King <paul.king.as...@gmail.com>
> > wrote:
> >
> > > I haven't used Geci, so can't really comment on all the things it
> > > might be capable of.
> > >
> > > With respect to something equivalent to Python doctests, in the Groovy
> > > project we
> > > have JavadocAssertionTestBuilder and JavadocAssertionTestSuite classes.
> > > Feel free to look to those for inspiration (at least).
> > >
> > > For Javadoc containing specially marked code blocks (assumes code is
> > > in <pre>...</pre> tags and has the special attribute
> > > class="groovyTestCase") the content is stripped out and placed into
> > > JUnit tests and run as a suite - giving the correct line number
> > > information if it fails. We do it for Groovy code but it could be done
> > > for just Java code.
> > >
> > > Examples:
> > >
> > > <pre class="groovyTestCase">assert [4,5] ==
> > > [1,2,3,4,5].intersect([4,5,6,7,8])</pre>
> > >
> > > /**
> > > * Randomly reorders the elements of the specified array.
> > > * <pre class="groovyTestCase">
> > > * Integer[] array = [10, 5, 20]
> > > * def origSize = array.size()
> > > * def copy = array.toList()
> > > * array.shuffle()
> > > * assert array.size() == origSize
> > > * assert copy.every{ array.contains(it) }
> > > * </pre>
> > > *
> > > * @param self an array
> > > * @since 3.0.0
> > > */
> > >
> > > You can stop using the JavadocAssertionTestSuite at any time.
> > > The code will still be in the Javadoc as documentation but just won't
> > > be tested any more as part of your test suite.
> > >
> > > P.S. I haven't used JavadocAssertionTestSuite with Maven, just Gradle.
> > >
> > > On Wed, Aug 28, 2019 at 11:43 AM Bruno P. Kinoshita <ki...@apache.org>
> > > wrote:
> > > >
> > > > In Python doctests are handy, where you can write documentation with
> > > code blocks, that can be executed with a unit-test running tool,
> validating
> > > the docs.
> > > > It's the first time I heard about Geci. But if you could perhaps show
> > > the pros and cons, what is the maintenance involved, whether it would
> > > change anything in the final binary that the user sees or not, and any
> > > other risks/issues.
> > > > If you are keen to show it in a PR, maybe just one or two examples
> would
> > > be enough to show how it works.
> > > > Thanks! And thanks for your recent contributions to Commons Lang too
> > > Peter.
> > > > Bruno
> > > >
> > > > On Wednesday, 28 August 2019, 1:00:50 am NZST, Peter Verhas <
> > > pe...@verhas.com> wrote:
> > > >
> > > > I have seen looking over the code of the LANG3 project that there
> are a
> > > lot
> > > > of places where the code is copy/paste. Many times these copy/paste
> code
> > > is
> > > > the result of the shortages of the Java language. We implement
> methods
> > > that
> > > > look more or less the same but they have to be created for all
> primitive
> > > > types. The maintenance of this code is cumbersome, changed at one
> place
> > > has
> > > > to be changed at the other places as well.
> > > >
> > > > The framework Java::Geci can automate the maintenance of those code
> > > > fragments. The framework is a test dependency ONLY, so it does not
> > > present
> > > > an extra dependency for the users.
> > > >
> > > > The application of the framework can also be used to automatically
> > > > copy/update code from the unit tests into the JavaDoc documentation,
> like
> > > > copying and converting assertion statements into tables with inputs
> and
> > > > results.
> > > >
> > > > I would be happy to create a few pull requests as a demonstration of
> how
> > > > Java::Geci can be used for the purposes.
> > > >
> > > > QUESTION:
> > > >
> > > > What is your attitude towards a new tool like this? I do not ask a
> final
> > > > decision for "yes we want to use it" or "no we do not want". I just
> want
> > > to
> > > > know if the developer community would consider the use of such a
> tool.
> > > >
> > > > A last note: The tool is extremely non-invasive. Any project using
> it can
> > > > decide at any point to discontinue the use. All it needs is to
> delete the
> > > > tests that start the tool, remove the dependency from the POM file
> and
> > > that
> > > > is it.
> > > >
> > > > --
> > > > Peter Verhas
> > > > pe...@verhas.com
> > > > t: +41791542095
> > > > skype: verhas
> > > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> > > For additional commands, e-mail: dev-h...@commons.apache.org
> > >
> > >
> >
> > --
> > Peter Verhas
> > pe...@verhas.com
> > t: +41791542095
> > skype: verhas
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
--
Peter Verhas
pe...@verhas.com
t: +41791542095
skype: verhas
