You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by David Blevins <da...@visi.com> on 2006/12/29 09:30:17 UTC
Documenting examples (was: Re: EJB3 Embedding tutorial avialable)
Hey All,
Figuring out a way to document our examples and get them on the
website has been in the back of my mind for a while. Since I created
that one example yesterday, I felt the pressure to bite that bullet
and finally took a stab at it. Let's see if I can't get some notes
out on it while I still remember all the details. Here goes...
First i created an empty wiki page and added four {snippet} macro
declarations pointing to the files in svn that I wanted to show from
the example. If I were to template that it'd look something like this:
h1. Overview
{snippet:url=openejb3/examples/telephone-stateful/README.txt}
h1. The Code
{snippet:url=openejb3/examples/telephone-stateful/src/main/java/
org/apache/openejb/examples/telephone/TelephoneBean.java|lang=java}
{snippet:url=openejb3/examples/telephone-stateful/src/main/java/
org/apache/openejb/examples/telephone/Telephone.java|lang=java}
{snippet:url=openejb3/examples/telephone-stateful/src/test/java/
org/apache/openejb/examples/telephone/TelephoneTest.java|lang=java}
Then I went through the source and added "tags" for the snippet macro
so I could chop out specific bits for usage in the wiki
documentation. You can do this by adding "START SNIPPET: foo" and
"END SNIPPET: foo" comments in your xml or java or whatever source.
Then you can add an "id" attribute to your {snippet} macros like so:
{snippet:id=foo|url=openejb3/examples/telephone-stateful/src/main/
java/org/apache/openejb/examples/telephone/Telephone.java|lang=java}
Then I went and slowly filled out the details, breaking things into
subsections and adding notes on EJB3 rules, etc. Several cycles of
that till you're satisfied.
So, I was committing like crazy while creating the doc and I'm left
wondering how I would go about this if I didn't have commit. I guess
in that scenario I'd probably get my example working, then I'd go
straight to the wiki and start creating a page for it. I'd forget
about the snippet macro and just copy/paste in the chuncks of code as
you'd typically do. When I was done creating the doc, I'd trim off
the overview and use it to create the README.txt file, then I'd see
what code chucnks I used and tag up all the source so we could
instead use the snippet macro once the code is committed. In short,
create your example, write your doc, then go back snippet-tag your
files and finally submit patch.
Anyway, hopefully we can get a wiki page for our website for each
example we have. We could send notifications to the user list when
done and also start a new section at the top right of our website
just for EJB3 Examples.
Any refinements/improvements welcome. If you end up tacking
documenting an example, feel free to take a fresh (i.e. totally
different) approach. Whatever get the job done :) Try and drop some
notes on the list if you do.
-David
On Dec 28, 2006, at 11:43 PM, David Blevins wrote:
> All,
>
> There is a new EJB3 tutorial/example available.
>
> This example shows how to use OpenEJB3's remoting capabilities in
> an embedded scenario to invoke an EJB3 Stateful bean local and over
> a network.
>
> http://cwiki.apache.org/OPENEJB/embedded-and-remotable.html
>
> It should download and run as-is, you will not need to build
> OpenEJB to run this example. You only need a current Maven 2 install.
>
> Comments, questions, criticisms, corrections welcome.
>
> As always, people are welcome to edit the wiki.
>
> -David
>
Re: Documenting examples (was: Re: EJB3 Embedding tutorial avialable)
Posted by David Blevins <da...@visi.com>.
On Jan 9, 2007, at 2:38 PM, Filippo Diotalevi wrote:
> On 12/29/06, Filippo Diotalevi <fi...@gmail.com> wrote:
>> David, the documentation template you have created is just great. We
>> probably should create an 'Examples' section in the wiki to group all
>> this kind of documents.
>> I'll send you the patches for the examples I created.
>
> David, I've created the documentation for the three example I wrote
> last December.
> I've reopened the corresponding issues, attached the patches and
> created the corresponding wiki pages. See:
> https://issues.apache.org/jira/browse/OPENEJB-346
> https://issues.apache.org/jira/browse/OPENEJB-347
> https://issues.apache.org/jira/browse/OPENEJB-357
>
Very excellent! These examples are really starting to look good!
Is there anyone out there in OpenEJB-land that can commit Filippo's
patches? I'm neck deep in Assembler code at the moment.
-David
Re: Documenting examples (was: Re: EJB3 Embedding tutorial avialable)
Posted by Filippo Diotalevi <fi...@gmail.com>.
On 12/29/06, Filippo Diotalevi <fi...@gmail.com> wrote:
> David, the documentation template you have created is just great. We
> probably should create an 'Examples' section in the wiki to group all
> this kind of documents.
> I'll send you the patches for the examples I created.
David, I've created the documentation for the three example I wrote
last December.
I've reopened the corresponding issues, attached the patches and
created the corresponding wiki pages. See:
https://issues.apache.org/jira/browse/OPENEJB-346
https://issues.apache.org/jira/browse/OPENEJB-347
https://issues.apache.org/jira/browse/OPENEJB-357
--
Filippo Diotalevi
filippo.diotalevi@gmail.com
http://www.diotalevi.com/weblog
http://www.jugmilano.it
Re: Documenting examples (was: Re: EJB3 Embedding tutorial avialable)
Posted by Filippo Diotalevi <fi...@gmail.com>.
On 12/29/06, David Blevins <da...@visi.com> wrote:
> Hey All,
>
> Figuring out a way to document our examples and get them on the
> website has been in the back of my mind for a while. Since I created
> that one example yesterday, I felt the pressure to bite that bullet
> and finally took a stab at it. Let's see if I can't get some notes
> out on it while I still remember all the details. Here goes...
David, the documentation template you have created is just great. We
probably should create an 'Examples' section in the wiki to group all
this kind of documents.
I'll send you the patches for the examples I created.
--
Filippo Diotalevi
http://www.diotalevi.com