From: "Si Chen" <[EMAIL PROTECTED]>
> Tibor,
>
> I tried to do exactly what you're suggesting about a year ago when we
> developed the Financials module. I tried to write a document which
> described all the business logic, data model, and processes. If you
> look in the financials module there is a docs/ directory with a
> TechnicalDocs file in DocBook SGML format.
>
> What I found was that it was extremely cumbersome and difficult to do
> things this way, because I was writing a document and then writing
> code. If later the code couldn't follow exactly the original design,
> I'd have to fix the code, then fix the document again. It is not
> impossible but would require a tremendous amount of discipline and
> effort to do this.
>
> A better solution, in my opinion, is to comment the code better--
> write more comments about the services, the Java methods, etc. that
> talk about what is going on, and comment the SECAs about what process
> each SECA is re-creating. This would create documentation which is
> easier for developers to maintain and which another developer who is
> familiar with the basic structure of OFBiz would be able to work with.
>
> This is what I'm trying to do know--as I look through code, I'm
> putting more comments and committing them. I would encourage you and
> everybody else to do the same. If you read through a service or some
> code that could use better comments, please send in a patch.
>
> Si
I agree with Si, especially if everybody think to update comments when modifying
code ...
Jacques
> On Jul 11, 2006, at 8:46 AM, tibor katelbach wrote:
>
> > I agree, that is the pb with such docs, they are heavy to write,
> > because the
> > task is huge. But once it is done the main part is done, offcourse
> > maintenance is heavy but it could also be a new way of spotting
> > precisly
> > what is new between versions and more readiable than a SVN upgrade.
> >
> > we all took the effort of understanding processes and this would be
> > a way to
> > share it. logs are shared but not exhaustive even the Verbose.
> >
> > I did it for quite a few processes and when I communicate these
> > docs to
> > other people needing a the same process, all they do is read it out.
> > if what they need is in there , then they dig in.
> > I often lost time by reading through loads of code and my answer
> > was just
> > waiting at the end,
> > this way you go directly to the interesting section.
> >
> > offcourse this gets really interesting only if we all participate.
> >
> > just trying to help newcomers
> >
> >
> > On 7/11/06, Chris Howe <[EMAIL PROTECTED]> wrote:
> >>
> >> I think that the easiest way to accomplish this is
> >> through the logs. Documenting these processes for
> >> reference would be too burdonsome and maintenance
> >> would be quite tedious.
> >>
> >> --- tibor katelbach <[EMAIL PROTECTED]> wrote:
> >>
> >> > Hi everyone
> >> > I've been tagging along an idea of documenting
> >> > algorythms of ofbiz
> >> > processes.
> >> >
> >> > Since I started working with ofbiz, as always I
> >> > found myself having to dig
> >> > into existing code
> >> > I found that the clearest way to understand how
> >> > modules work is to rebuild
> >> > the algorithm behind a process .
> >> > A process could be a complete run through from url
> >> > to controller to to
> >> > Service , run through the Service to result , to
> >> > Screen ...etc.
> >> >
> >> > by writting down the main elements of a process this
> >> > draws quite a clear map
> >> > of the algorithm behind the process, and especially
> >> > is easily transmitable and readable by others. This
> >> > also keeps from having
> >> > to run through all code , all processes which would
> >> > be the next step after
> >> > reading the algo.
> >> >
> >> > WDYT ?
> >> >
> >> > I think it would be enourmously enrichining for
> >> > people like myself wanting
> >> > to understand quickly what does what, and what is
> >> > done behind the scenes.
> >> >
> >> > Sometimes these algos quite large for processes like
> >> > the chekout process
> >> > here's a sample I gathered up for the tellafriend
> >> > process:
> >> > I list Service , Maps, redirections... a std format
> >> > needs to be set up
> >> >
> >> > Form : tellafriend
> >> > input : message, sendTo, sendFrom
> >> >
> >> > >>>> controller event :
> >> > org.ofbiz.product.product.ProductEvents"
> >> > invoke="tellAFriend"
> >> >
> >> > >>> dans le service tellafriend
> >> >
> >> > [GenericEntity:ProductStoreEmailSetting]
> >> >
> >>
> >> [bccAddress,null()][bodyScreenLocation,null()][ccAddress,null()]
> >> [contentType,null()][createdStamp,2006-04-21
> >> > 15:06:47.428(java.sql.Timestamp)]
> >> > [createdTxStamp,2006-04-21
> >> > 15:06:46.848(java.sql.Timestamp
> >> > )][emailType,PRDS_TELL_FRIEND(java.lang.String)]
> >> >
> >> [fromAddress,[EMAIL PROTECTED](java.lang.String
> >> )][lastUpdatedStamp,2006-04-21
> >> > 15:06:47.428(java.sql.Timestamp)]
> >> > [lastUpdatedTxStamp,2006-04-21
> >> > 15:06:46.848(java.sql.Timestamp
> >> > )][productStoreId,910(java.lang.String)]
> >> > [subject,${sendFrom} has sent you a
> >> > link!(java.lang.String)]
> >> >
> >> [templatePath,/applications/petitbateau/templates/email/
> >> tellafriend.ftl(
> >> > java.lang.String)][xslfoAttachScreenLocation,null()]
> >> >
> >> > {
> >> > templateData=
> >> > [
> >> > [EMAIL PROTECTED],
> >> > message=qgfgsdf gsdf gsdf gsdfg sdf,
> >> > [EMAIL PROTECTED],
> >> >
> >> pageUrl=http://localhost/petitbateau/control/product?product_id=94451
> >> > ],
> >> >
> >> > [EMAIL PROTECTED],
> >> >
> >>
> >> templateName=X:/X_Dev/sequoiaerp/applications/petitbateau/
> >> templates/email/tellafriend.ftl,
> >> >
> >> > sendCc=null,
> >> > sendBcc=null,
> >> > [EMAIL PROTECTED] has sent you a link!,
> >> > [EMAIL PROTECTED],
> >> > contentType=null}
> >> >
> >> >
> >> >>>>dispatcher.runAsync("sendGenericNotificationEmail",
> >> > context);
> >> > >>>>org.ofbiz.content.email.NotificationServices"
> >> > invoke="sendNotification(DispatchContext ctx, Map
> >> > context)
> >> > >>>>method prepareNotification(ctx, context);
> >> > //builds the body of the
> >> > mail by rendering the corresponding ftl
> >> > >>>>if body != null
> >> > >>>>dispatcher.runSync("sendMail", emailContext);
> >> > org.ofbiz.content.email.EmailServices"
> >> > invoke="sendMail"
> >> >
> >> >
> >> >
> >> > Regards
> >> > Tibor
> >> >
> >>
> >>
