Documentation & Examples

---------- snip ------------
> file together with your (slightly obfuscated) email address. If you
> don't want your email address in the file, or if you want your polrtex
> (at) users.sourceforge.net address instead, please feel free to update
> the file.

I fixed the email and committed the document. It feels good, this was the
first time I committed something directly to sourceforge, that was a great
birthday present (for Aug.19 ;-) ). I added my sourceforge address: as
much as I love my job at the current place, there is a good chance that I
will be contributing to sourceforge long after I'm outta here.


> You may wonder why I have wrapped the lines from your patch. I of course
> know that this has no influence on the final HTML whether the lines are
> wrapped or not, but it makes it a little easier to do changes in the
> text later, without causing diff tools to mark the entire section as
> changed (as most diff tools are line based).

Thank you for fixing it up, I wasn't sure how you wanted it formatted, it
looks great now.


> That sound really great, have you considered making these examples as
> test-cases? Check the org.jawin.InstructionTest in the test-src branch
> at the Java side, and the cpp/CallCOMUnitTest/instructionTests.cpp on
> the native side. You should be able to run the tests with the "ant test"
> target - please email me if you gets classpath problems, as it at least
> needs junit.jar.

I will add the examples that I was considering in a separate test case : I
would rather use the Win32 functions as the C-side of my tests, because I
really don't have a good setup for building the native side of Jawin.
Actually, I have VS.NET installed (and I guess I could build the native
side as well), but when I open the project it attempts to convert it to
its own project format. I don't want to mess up the setup that you are
using, so I will be very careful not to accidentally commit the project
files. Btw, what environment do you use to build it ?

>
> > Along these
> > lines, I was wondering : why does the Transform.cpp use literals in
the
> > process() method, instead of using the pre-defined values from
> > instructions.h ?
>
> :-) - this is probably one of the parts of Jawin that needs a little
> cleanup.

I will take this on: I'll substitute the literals in the Transform.cpp
with the appropriate constants defined in the header file.

> >         I am also working on a Parameters class that would automate &
> > simplify most of the basic instruction string building, some of the
> > marshalling of ints, strings, buffers, etc, and stack size
calculations. I
> > will provide that together with the generated structs from VJ++. For
> > handling structs, my idea is to basically  extend the Struct classes
> > created by VJ++ (which contain all data elements), and have the child
> > class implement a predefined interface (e.g. JawinCStruct), which will
> > define the operations that will be necessary for the Parameters class
> > (e.g. marshal, marshallOut, size, token, etc).
> >
>
> Sounds exciting, although I am not sure I understand it 100%, but I am
> looking forward to see the code.


I will try to produce some code in the next week or to or so to
demonstrate what I mean. I will probably try to wrap it up in a test case,
that should be pretty good at illustrating the idea. Basically, as I was
trying to invoke some win32 functions, I found myself writing over and
over the same pieces of code (e.g. the marshalling in and out of the
streams, the instruction string building, calculating the stack size) -
that was a pretty good hint that the repeated functionality has to be
encapsulated in a separate class.

>
> Best Regards, and thanks for the effort you puts into Jawin.

Well, I have to thank you for this - you are the genius who made this up,
I'm just the ant that brings his contribution to the anthill...

Regards,

Alex Kotchnev
Developer / Systems Analyst
Diversified Information Technologies

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CONFIDENTIALITY NOTICE: If you have received this e-mail in error, please
immediately notify the sender by e-mail at the address shown.  This e-mail
transmission may contain confidential information.  This information is
intended only for the use of the individual(s) or entity to whom it is
intended even if addressed incorrectly.  Please delete it from your files
if you are not the intended recipient.  Thank you for your compliance.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++