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

[Antonio Goncalves]

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