Hi Jonathon, I guess all is almost said in https://issues.apache.org/jira/browse/OFBIZ-1387 now
Jacques De : "Jonathon -- Improov" <[EMAIL PROTECTED]> > > 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. > >> > > > > >
