Re: [jira] Commented: (OFBIZ-1387) comment Entities

[Jonathon -- Improov]

> the ModelFormField.getTitle method exists and do what David suggested. How to
> use it in entities fields documentation is another thing I have not already
> think about.
You mean generate the documentation automatically (from the CamelCase field names) and write them 
to the entitymodel.xml files? Or write this documentation to some page in webtools?

> Yes I agree. I guess this comes from my suggestion to Adrian (document all
> fields). In french we have an expression for that "L'enfer est pavé de bonnes
> intentions"

We have the same saying too, about good intentions.

There's another one I use in life. If I think others are contributing 10% and I 90%, then it is 
more like 50% and 50%. Currently, it seems to me that Adrian is contributing 90% and I 10%, so... :P

> For me, code meant also xml files, like entitiemodel.xml

Those entitymodel.xml files don't exactly contain tons of codes (like in Java or bsh or ftl 
files). So, I guess it'll be less painful to see docs being inserted every now and then, which 
will every now and then make me jump and think "oh no, I gotta reconcile new updates into my work 
copies". Reconcile means merge into my custom OFBiz branches.

I think it's ok to add docs to entitymodel.xml files. But to add it to Java codes can be painful 
to maintainers like me. :(

What do you think about creating docs on a separate SVN branch (not OFBiz)? You know DocBook? We 
could write a translator that translates the entitymodel.xml into DocBook format, so we just "fill 
in the blanks" to add documentation to each entity or field. That way, the codes won't be touched, 
and the only updates going into them are code changes.

I understand it's desirable to put docs into codes themselves, and be able to generate up-to-date 
Javadocs from those documented codes. I tried this for years, long ago. It was a nightmare as we 
struggled to keep track of "actual code changes" among the many insertions of docs. Throws a 
spanner into version control of codes. Works great for version control of docs, though.

Whatever path we take, it will still be great to have docs for the data model. I'd rather take 
whatever docs that are contributed now, than enforce rules to discourage contributors. So, 
wherever the docs may be, if they are good docs, they are in the "right" place. :)

Jonathon

Jacques Le Roux wrote:
Jonathon,

I prefer to reply on dev ML to not overload the Jira issue (my primariy intent 
with this comment was to abstract ;o)

De : "Jonathon Wong (JIRA)" <[EMAIL PROTECTED]>
    [
https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545000
 ]
Jonathon Wong commented on OFBIZ-1387:
--------------------------------------

We should use a small method that adds spaces and changes capitalization from
fields names enough obvious to describe succinctly the fields (like in the
form widget : ModelFormField.getTitle)
I thought this was a playful or slightly sarcastic joke by David? A rhetorical? 
I don't think it is useful to explain a field like
"contactMechId" as "Contact Mech Id".

Maybe, but the ModelFormField.getTitle method exists and do what David 
suggested. How to use it in entities fields documentation is
another thing I have not already think about.

We should document non obvious fields and related concepts directly where
fields are defined (entitymodel.xml files). Though Scott suggested to
document those concepts at the data model level (like for instance why
contact mechs are not being deleted but expired). But where will stand this
documentation at the data model level is obscure to me. I guess out of the
code in official documentation (Confluence).
Well, first, we do need to humbly admit that documentation depends on manpower. 
As David already expressed, the OFBiz community is
enormously grateful for any documentation attempts.
The particular thing that hit David (IMO) was the fact that the documentation 
was obviously pointless, and falsely flags a
"change" or "improvement" in the SVN (thru commits and log that might say "added 
documentation, really"). Spurious updates, pardon
me, so to speak.

Yes I agree. I guess this comes from my suggestion to Adrian (document all 
fields). In french we have an expression for that
"L'enfer est pavé de bonnes intentions"

As for where documentation should reside, frankly, I don't want to be choosy. 
If it's great documentation (not pointless ones), I
don't care if I read it in the codes or in the data model or in Confluence. 
When we got time, we'll file up those great
documentation snippets properly. But the point is that somebody spent time to 
contribute a useful snippet that's a keeper.
Note how documentation doesn't hurt the OFBiz codes, so it really doesn't 
matter where they go.

Oh, wait. This just dawned on me. Putting docs in the codes will falsely flag 
"changes", which will make me think "ah, the codes
in that file changed, I must reconcile the new updates". Ok, I'm voting against 
putting docs in the codes.

Héhé, pretty egocentric isn'it ;o) ?

If a "pointer" or "hyperlink" must be inserted into the codes to point coders to online 
docs, then can we have an online "Javadoc"
of all the codes (Java classes, scripts, etc) and put our "pointer to docs" 
there? Not in the codes, please.

I did not think about inserting "hyperlinks" in code. In my mind "pointers" were a 
mean to reach something by searching it "by
hand", like "look in the Data model Resource book page x". Your suggestion is 
great for the java part. For me, code meant also xml
files, like entitiemodel.xml (remember we were speaking about that ;o) . I did 
not thought about the bsh/ftl couple which is mostly
at the end of the branches and should not need much high level documentation 
but in place comments). This remains us that AFAIK we
still dont have an updated Javadoc online as it was in pre-Apache times. Andrew 
Sykes provided one last yeat at http://www.ofbiz.eu/
but it's not updated any longer. I will try to provide one on my poor man 
server and as I hope to change my dev. machine I will then
provide a real server later in 2008. But with still a poor bandwidth as it's in 
my home with a 128/512 countryside ADSL connection.
Though I read lately that is could changed in some months also. OK, I stop to 
tell my life..    .

Codes could have low-level docs for coders, we could add those, yes. But 
frankly, if a coder has gone that deep into OFBiz codes,
he is already prepared to walk the codes himself, and wouldn't complain that 
there are no docs!

Doc is always helpful. There is only one problem with it in code : it has to be 
updated and this is not always obvious even with
goodwills (when it refers from 100 lines below or above for instance, blocks 
are sometimes long....). Javadoc is great in any case !

I will begin by create a Glossary in Confluence, any help is welcome :o)

Jacques

comment Entities
----------------

                Key: OFBIZ-1387
                URL: https://issues.apache.org/jira/browse/OFBIZ-1387
            Project: OFBiz
         Issue Type: Task
         Components: accounting, content, ecommerce, framework, humanres, 
manufacturing, marketing, order, party, pos, product
           Reporter: BJ Freeman
           Assignee: Adrian Crum
        Attachments: party_entity_model.patch


comment the Entities files in the entitymodel.xsd
put a comment in this jira of the entities you are going to comment
when you attact your patch number it with a date, so if you don't do the whole 
thing someone else can add to it, and not
overwrite your patch.
hope the committers don't mind this break in the rules.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.