[jira] Created: (OFBIZ-1387) comment Enities
Locked
12
12
[jira] Created: (OFBIZ-1387) comment Enities
 
|
comment Enities
--------------- Key: OFBIZ-1387 URL: https://issues.apache.org/jira/browse/OFBIZ-1387 Project: OFBiz Issue Type: Task Components: accounting, assetmaint, content, ecommerce, framework, hhfacility, humanres, manufacturing, marketing, order, party, pos, product Reporter: BJ Freeman 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. |
[jira] Commented: (OFBIZ-1387) comment Enities
|
|
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12540649 ] BJ Freeman commented on OFBIZ-1387: ----------------------------------- I am working on orderItem and OrderHeader > comment Enities > --------------- > > Key: OFBIZ-1387 > URL: https://issues.apache.org/jira/browse/OFBIZ-1387 > Project: OFBiz > Issue Type: Task > Components: accounting, assetmaint, content, ecommerce, framework, hhfacility, humanres, manufacturing, marketing, order, party, pos, product > Reporter: BJ Freeman > > 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. |
[jira] Updated: (OFBIZ-1387) comment Enities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Adrian Crum updated OFBIZ-1387: ------------------------------- Component/s: (was: assetmaint) (was: hhfacility) I removed the asset maintenance and hhfacility components - they don't have unique entities. BJ, Keeping the file names the same would be fine - as long as there is a comment stating that the more recent versions are the more complete ones. > comment Enities > --------------- > > 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 > > 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. |
[jira] Updated: (OFBIZ-1387) comment Enities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Adrian Crum updated OFBIZ-1387: ------------------------------- Attachment: party_entity_model.patch Attached file (party_entity_model.patch) is for review. I added some field descriptions. I'm wondering how far we want to go with this. Some field names are self-explanatory - do we include descriptions for those? If we choose not to include some descriptions, what would be the criteria for that decision? This patch works best with the patch in OFBIZ-1389 . > comment Enities > --------------- > > 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 > 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. |
[jira] Commented: (OFBIZ-1387) comment Enities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12541530 ] Jacques Le Roux commented on OFBIZ-1387: ---------------------------------------- Hi Adrian, IMHO I think we should not succomb at the temptation. All fields should be documented since in certain cases the name might not be available. > comment Enities > --------------- > > 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 > 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. |
[jira] Issue Comment Edited: (OFBIZ-1387) comment Enities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12541530 ] jacques.le.roux edited comment on OFBIZ-1387 at 11/10/07 4:36 AM: ------------------------------------------------------------------ Hi Adrian, IMHO I think we should not succomb to the temptation. All fields should be documented since in certain cases the name might not be available. was (Author: jacques.le.roux): Hi Adrian, IMHO I think we should not succomb at the temptation. All fields should be documented since in certain cases the name might not be available. > comment Enities > --------------- > > 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 > 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. |
[jira] Updated: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Jacopo Cappellato updated OFBIZ-1387: ------------------------------------- Summary: comment Entities (was: comment Enities) > 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 > 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. |
[jira] Assigned: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Adrian Crum reassigned OFBIZ-1387: ---------------------------------- Assignee: Adrian Crum > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12544838 ] Adrian Crum commented on OFBIZ-1387: ------------------------------------ As of rev 596821 all of the description elements in entitymodel.xml will appear in the Entity Reference screen in the webtools component. > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12544876 ] Adrian Crum commented on OFBIZ-1387: ------------------------------------ The Party component has a portion of its entitymodel.xml file documented as of rev 597479. Still needs more work. > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12544904 ] BJ Freeman commented on OFBIZ-1387: ----------------------------------- Descriptions really should be for explaining non-obvious use and purposes of elements, and if there isn't anything non-obvious then there is no need for a description. General information about from/thru dates, types, etc can be found in the entity overview on docs.ofbiz.org. > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12544960 ] Jacques Le Roux commented on OFBIZ-1387: ---------------------------------------- An interesting discussion has taken place in dev ML : http://www.nabble.com/Re%3A-svn-commit%3A-r597479----ofbiz-trunk-applications-party-entitydef-entitymodel.xml-tf4858720.html I try to give an abstract below The main idea is to avoid redundancy in documentation while giving enough and useful informations without over-documenting (as it well known : too much information kills information) Pragmatically . 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) . 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). There we could explain this kind of concepts which are so often re-explained in ML. But who read documentation ? Not Skip for sure who prefer to see it in the code ;o) Theoritically (a point I like personnaly) Jonathon : <<Documenting a single concept *concisely* in multiple places is good. That's where "too much documentation" doesn't hold. Cross-references between those multiple places will be better. A highly connected documentation is like a highly connected brain with fast memory retrieval speeds.>> (I think Jonathon means like Google did : bringing us synaptic connections, not only neurons) Defining concepts like Party and Contact Mech should be done concisely in a glossary at a high level in the documentation with reference to OFBiz Bible (Len SIlverston's books) when needed. Like Apache do it here : http://www.apache.org/foundation/glossary.html. And as suggested Jonathon above providing links (directly accessible thru browser) or pointers (in code or such) will be a must of course. Thanks to all > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ 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". > 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. 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. 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. 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! > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545019 ] BJ Freeman commented on OFBIZ-1387: ----------------------------------- I am reminded of a saying: there are Dreamers that come up with wonderful Ideas todo. there are doers that are really good and getting something practical done. The problem is that the Dreamer and Doer don't speak the same language so it is hard to get the concept from the dreamer to the doers. This brings in a third type person which understands the dreamers enough and is able to communicate in a way the doers can accomplish something. In this case documentation at a level the doers can get something done. > 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. |
Re: [jira] Commented: (OFBIZ-1387) comment Entities
Administrator
|
In reply to this post by Nicolas Malin (Jira)
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)" <[hidden email]> > > [ 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 > > 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. > |
|
|
> 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)" <[hidden email]> >> [ > 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. >> > > |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545072 ] Adrian Crum commented on OFBIZ-1387: ------------------------------------ Thank you BJ, Jacques, and Jonathon. Now we have a clearer picture of what we're trying to accomplish with this issue. Regarding where documentation should go: I liked the idea of having it in the entity definition - similar to JavaDocs being in the code they describe. My hope was to use the embedded documentation to generate a PDF file that could be placed on the Wiki. With a system like that in place, developers aren't expected to maintain a separate document. > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545080 ] Jacopo Cappellato commented on OFBIZ-1387: ------------------------------------------ I totally agree with Adrian's last comment. One more note: it would be nice, in my opinion, that in the PDF doc (or in the Webtools HTML reference, if the description of the field is empty or missing then the automatic conversion from the field name is shown (productId-->Product Id). Jacopo > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545121 ] Skip Dever commented on OFBIZ-1387: ----------------------------------- I too agree with Adrian's method because it puts the comments in two easy to get at places. Javadocs or types like this are great ways to document stuff. Jonathon wrote: "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!" Jonathon, I agree, but what about the next guy to come alone. How much wasted man-power does it take walking through the code before someone realizes how this wasted time could be put to better use. It is my view that if someone commits a Javadoc entry in the code, that commit should be reviewed and added pronto (maybe with a change log at the top indicating that no code has been changed for those like me who are paranoid about adding changed code without a serious beta test.) > 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. |
[jira] Commented: (OFBIZ-1387) comment Entities
|
|
In reply to this post by Nicolas Malin (Jira)
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545124 ] BJ Freeman commented on OFBIZ-1387: ----------------------------------- Ok two things 1) can we also include Service in this maybe change to add comments to entities, services, and simple methods. 2)here is what i mean about documentation. <description> if you don't assign a productID, one will be autogenerated </description> > 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. |
«
Return to OFBiz - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |