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

[Antonio Goncalves]

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/>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/forge-dev/attachments/20150307/6f5fb66d/attachment.html