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
