You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by "BJ Freeman (JIRA)" <ji...@apache.org> on 2007/11/07 01:55:50 UTC
[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 Entities
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545171 ]
Jacques Le Roux commented on OFBIZ-1387:
----------------------------------------
I think that Adrian proposition got a good consensus (I like it too of course)
Combining BJ's and Skip's last comments and using the tooltip attribute (example/control/FormWidgetExamples) we should end up with a raisonnable solution for Widget rendering :o).
I'm not quite sure why we ended this the current solution for tooltips in Widget (some field types do not have the title attribute, I remind me vaguely). Now I wonder if in a mid term we should not prefer to use a solution like http://ajaxian.com/archives/2005/11#post-564 to render tooltip. The obvious idea is to unclutter the UI...
I'm not quite sure to understand BJ's 1st question.
Is it ?
1) Can we also include Service in this ? Maybe change to add comments to entities, services, and simple methods ?
If yes, there are already means to document services and simple-methods so I guess BJ you mean to produce an external document from them ?
. In simple-methods short-description (required, used in certain error messages)
. In service description (not required. Should be, to be consistent with simple-method ?)
One point which could be very interesting for developpers is to continue the effort in documenting the XSD files (using annotation/documentation, AFAIK only simple-method.xsd is completly done : OFBIZ-1398)
Thanks
> 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] Closed: (OFBIZ-1387) comment Entities
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Adrian Crum closed OFBIZ-1387.
------------------------------
Resolution: Fixed
I'm closing this because I believe most of the things we agreed upon in the comments have been implemented. If anyone wants to do more work adding descriptions to entity definitions, they can open a new issue.
> 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, product, specialpurpose/pos
> 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 Enities
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ 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] Commented: (OFBIZ-1387) comment Entities
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ 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
Posted by "Skip Dever (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545230 ]
Skip Dever commented on OFBIZ-1387:
-----------------------------------
I guess I want clear. I agree that having localized documentation is a huge job done no where else in Ofbiz. What I was talking about was Adrians idea of getting the field definition text to display and possibly a tool tip.
> 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
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545221 ]
Jacques Le Roux commented on OFBIZ-1387:
----------------------------------------
David,
If we really want to use it in UI, for consistency, i18n seems better to have than not. So it comes back to question "do we really want to use it in UI" ?
About XML : is there in place an l10n mechanism as for properties files (which we know as implemented by Sun is a bit deficient) ?
> 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
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545246 ]
Jacques Le Roux commented on OFBIZ-1387:
----------------------------------------
Adrian, Skip,
What would think non english speaking users when all the UI would be localised and tooltips would not ?
So what I intended to say is : If we do not localise the embedded documentation (this issue is all about embedded documentation) then we should not provide a mean to show tooltips not localised. BTW I agree that anyway localising embedded documentation would be a real prowess and is not really needed. The root of our misunderstanding is that we shall not mix embedded documentation targetted to developpers and tooltips targetted to end-users.
If you don't mind I would prefer to continue this discussion on the new specialised issue Adrian created : OFBIZ-1425
Thanks
> 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
Posted by "Skip Dever (JIRA)" <ji...@apache.org>.
[ 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
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ 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] Updated: (OFBIZ-1387) comment Enities
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ 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 Entities
Posted by "Jacopo Cappellato (JIRA)" <ji...@apache.org>.
[ 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] Commented: (OFBIZ-1387) comment Entities
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545183 ]
Adrian Crum commented on OFBIZ-1387:
------------------------------------
I've been thinking about Jacopo's suggestion and I think I came up with a strategy for the ModelField.getDescription method:
1. Get description from entitymodel.xml
2. If that's empty, lookup description in a properties file (for common, redundant fields)
3. If that's empty, parse the field name into words - as Jacopo suggested
So, a properties file could contain:
productId=A unique product ID
And the Product.productId entity definition could contain:
<description>If you don't assign a productID, one will be autogenerated</description>
Calling ModelField.getDescription on Product.productId would return "If you don't assign a productID, one will be autogenerated" and calling ModelField.getDescription on the productId field of any other entity would return "A unique product ID"
Properties files could be organized by entity package names - that would help prevent field name clash.
Using the field description for tooltips wouldn't work because the description is in English. I like the idea of getting a tooltip from ModelField, but I believe it should be a separate method - that performs a lookup in a properties file.
> 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
Posted by "Jacopo Cappellato (JIRA)" <ji...@apache.org>.
[ 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
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545174 ]
Jacques Le Roux commented on OFBIZ-1387:
----------------------------------------
Maybe we can add a description attribute for ECA also ?
About making mandatory descriptions for services and ECA, for legacy reasons we may automatically put a blank in descriptions when there are none (not sure if we could need to put it by a script or something or accept old services without descriptions)
> 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
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ 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
Posted by "Skip Dever (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545125 ]
Skip Dever commented on OFBIZ-1387:
-----------------------------------
One other thing occured to me concerning documenting fields in the entitymodel.xml file. If the fields contained a descriptive tag where the field name might not be obvious (not like partyId = Party Id), it could be used to auto-generate entry screens to supply a tooltip or a second field to provide the text to the left of the entry field. This text could be like ${UILabel.field1Text}.
> 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
Posted by "David E. Jones (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545220 ]
David E. Jones commented on OFBIZ-1387:
---------------------------------------
Do we really want to worry about localized documentation for this case? In general we have not anywhere else in OFBiz for this sort of "embedded" documentation.
If we do something like that, here or anywhere, we should use XML and not properties files. XML is about 1E6 times better than properties files (name/value pairs) for organizing this sort of information. It is hierarchical so much easier to organize and you can use real UTF-8 characters there instead of having to encode everything and use a special tool or a translator to work on the files.
> 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
Posted by Jacques Le Roux <ja...@les7arts.com>.
Hi Jonathon,
I guess all is almost said in https://issues.apache.org/jira/browse/OFBIZ-1387 now
Jacques
De : "Jonathon -- Improov" <jo...@improov.com>
> > 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)" <ji...@apache.org>
> >> [
> >
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.
> >>
> >
> >
>
Re: [jira] Commented: (OFBIZ-1387) comment Entities
Posted by Jonathon -- Improov <jo...@improov.com>.
> 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)" <ji...@apache.org>
>> [
> 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.
>>
>
>
Re: [jira] Commented: (OFBIZ-1387) comment Entities
Posted by Jacques Le Roux <ja...@les7arts.com>.
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)" <ji...@apache.org>
>
> [
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
Posted by "Jonathon Wong (JIRA)" <ji...@apache.org>.
[ 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
Posted by "BJ Freeman (JIRA)" <ji...@apache.org>.
[ 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.
[jira] Commented: (OFBIZ-1387) comment Enities
Posted by "BJ Freeman (JIRA)" <ji...@apache.org>.
[ 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] Commented: (OFBIZ-1387) comment Entities
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ 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] Assigned: (OFBIZ-1387) comment Entities
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ 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
Posted by "Skip Dever (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545184 ]
Skip Dever commented on OFBIZ-1387:
-----------------------------------
Adrian
Dude, this is brilliant!
> 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] Issue Comment Edited: (OFBIZ-1387) comment Enities
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ 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] Commented: (OFBIZ-1387) comment Entities
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545227 ]
Adrian Crum commented on OFBIZ-1387:
------------------------------------
David,
No, we don't need to worry about localized documentation. The embedded documentation is in English. The localized documentation is an unintended side-effect of having an alternate file to look up documentation.
> 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] Updated: (OFBIZ-1387) comment Enities
Posted by "Adrian Crum (JIRA)" <ji...@apache.org>.
[ 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 Entities
Posted by "BJ Freeman (JIRA)" <ji...@apache.org>.
[ 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
Posted by "BJ Freeman (JIRA)" <ji...@apache.org>.
[ 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.
[jira] Commented: (OFBIZ-1387) comment Entities
Posted by "Jacques Le Roux (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12545216 ]
Jacques Le Roux commented on OFBIZ-1387:
----------------------------------------
Adrian, Skip,
It's great but I don't quite like the idea of having 2 sources of documentation. I would prefer to have this information only in properties files for the sake of localisation purpose as it already exists for enumerations for instance (*EntityLabels*.xml). Am I missing something apart to have the documentation directly in entitymodel. xlm files ?
> 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.