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. >
