[forge-dev] Feedback on Documenting how to create and test a command that creates Java code

Sun Mar 8 10:14:56 EDT 2015

Hi Antonio,

I've incorporated some changes in the following areas:

   - Fixed typos
   - Provided some more explanation on how the command name translates in
   the shell and in the IDEs
   - Gradually introduce the command test APIs

About the other points from my feedback, I'm afraid I cannot explain much
the Addon deployment stuff and detailed descriptions of facets may not be
really appropriate for this tutorial.

Will look at the second tutorial tonight or in the course of the next few
days.

Cheers,
Ivan

On Sat, Mar 7, 2015 at 4:29 PM, Antonio Goncalves <antonio.mailing at gmail.com
> wrote:

> BTW, I've just added a second tutorial. Based on the first one (generated
> a single Java EE class) but adding some extra parameters (not just named
> and targetPackage).
>
> Antonio
>
> 2015-03-05 22:19 GMT+01:00 Ivan St. Ivanov <ivan.st.ivanov at gmail.com>:
>
>> Thanks, Antonio! I'll take some time during the weekend to fix the low
>> hanging fruit :)
>>
>> On Thu, Mar 5, 2015 at 2:26 PM, Antonio Goncalves <
>> antonio.mailing at gmail.com> wrote:
>>
>>>
>>>
>>> 2015-03-04 22:47 GMT+01:00 Ivan St. Ivanov <ivan.st.ivanov at gmail.com>:
>>>
>>>> Hi everybody,
>>>>
>>>> I went a few times through the tutorial on writing Java source Forge
>>>> commands. Great effort! It was about time we have things like this (which
>>>> is more a bad feedback for me, as I wanted to write something like this for
>>>> quite a long time, but I haven't yet done it ;)).
>>>>
>>>> So, here is some things that I think can be improved:
>>>>
>>>> - Shouldn't the FAQ and the tutorial be separate documents?
>>>>
>>>
>>> Yes, that's the idea
>>>
>>>
>>>
>>>> - Where did the UML diagram of the commands type structure go?
>>>>
>>>
>>> It's here https://issues.jboss.org/browse/FORGE-2109
>>> I took it off because it's not what we have at the moment. I've started
>>> some refactoring so we would end up with a cleaner class hierarchy.
>>>
>>>
>>>> - According to the title and to the introductory paragraphs of the
>>>> tutorial section, a reader would feel that this is a generic paper about
>>>> writing Forge commands in their own addon (something like in the Developing
>>>> Forge section in the HoL). However, it is more about extending existing
>>>> [core] addons with new commands. So maybe this could be stated more
>>>> explicitly in the title?
>>>>
>>>
>>> Good point
>>>
>>>
>>>
>>>> - The Metada.name method gets a string which is by convention something
>>>> like "<command group>: <command name>". Maybe it could be explained how
>>>> would this translate on the command line and in the IDE, what are the
>>>> common command groups and what is the convention for the command names
>>>>
>>>
>>> Feel free to explain it, I didn't know there was such a structure, I
>>> thought it was just free text (I don't use IDEs, just CLI ;o)
>>>
>>>
>>>
>>>> - I personally need a better explanation about the difference between
>>>> @AddonDeployments and ShrinkWrap.addAsAddonDependenies
>>>>
>>>
>>> Yes, I asked a few question to Lincoln and George. Their answer were ok,
>>> but I would like to have a deeper explanation.
>>>
>>>
>>>
>>>> - It would be clearer if the UITestHarness and ShellTest classes and
>>>> their purpose should be introduced right before the test methods that they
>>>> are used in (checkCommandMetadata and checkCommandShell respectively) and
>>>> not in the beginning of the section. Thus the reader does not lose the
>>>> context around those test helper classes at the point they are used for the
>>>> first time
>>>>
>>>
>>> Hum... I don't get it, feel free to update the doc
>>>
>>>
>>> - In the beginning of the Let's add some business code section you
>>>> refresh the readers about our goal (i.e. to create a constraint class), but
>>>> not about the Forge command that we wrote before the test section. It may
>>>> be a good idea to remind the reader about that as well, so that she does
>>>> not have to scroll up to find what she did so far
>>>>
>>>
>>> Done
>>>
>>>
>>>
>>>> - It would be a good idea to have a few sentences about what is a facet
>>>> before it is introduced for the first time in testCreateNewPayload method
>>>>
>>>
>>> I don't know much about it, so if you have some knowledge, feel free to
>>> change it.
>>>
>>>
>>>> - There are some typos
>>>>
>>>> I suppose that you can turn reviewing on and I can do myself some of
>>>> the most obvious fixes (like the typos for example), which you can review
>>>> afterwards?
>>>>
>>>
>>>
>>> I've added you write access to the doc. Feel free to
>>> change/comment/correct it
>>>
>>> Thanks Ivan for your feedback
>>>
>>> Antonio
>>>
>>>
>>>>
>>>> Cheers,
>>>> Ivan
>>>>
>>>> _______________________________________________
>>>> forge-dev mailing list
>>>> forge-dev at lists.jboss.org
>>>> https://lists.jboss.org/mailman/listinfo/forge-dev
>>>>
>>>
>>>
>>>
>>> --
>>> Antonio Goncalves
>>> Software architect and Java Champion
>>>
>>> Web site <http://www.antoniogoncalves.org/> | Twitter
>>> <http://twitter.com/agoncal> | LinkedIn
>>> <http://www.linkedin.com/in/agoncal> | Paris JUG
>>> <http://www.parisjug.org/> | Devoxx France <http://www.devoxx.fr/>
>>>
>>> _______________________________________________
>>> forge-dev mailing list
>>> forge-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/forge-dev
>>>
>>
>>
>> _______________________________________________
>> forge-dev mailing list
>> forge-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/forge-dev
>>
>
>
>
> --
> Antonio Goncalves
> Software architect and Java Champion
>
> Web site <http://www.antoniogoncalves.org/> | Twitter
> <http://twitter.com/agoncal> | LinkedIn
> <http://www.linkedin.com/in/agoncal> | Paris JUG
> <http://www.parisjug.org/> | Devoxx France <http://www.devoxx.fr/>
>
> _______________________________________________
> forge-dev mailing list
> forge-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/forge-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/forge-dev/attachments/20150308/8abd77f8/attachment-0001.html 