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.:
//@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
