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

[Ivan St. Ivanov]

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