OFBiz › OFBiz - Dev

[jira] Created: (OFBIZ-1387) comment Enities

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

33 messages Options

Nicolas Malin (Jira)

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

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

Nicolas Malin (Jira)

[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_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

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

[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_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)

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

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

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

[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_12545184 ]

Skip Dever commented on OFBIZ-1387:
-----------------------------------

Adrian

Dude, this is brilliant!

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Jacques Le Roux

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

Administrator

In reply to this post by jonwimp

Hi Jonathon,

I guess all is almost said in https://issues.apache.org/jira/browse/OFBIZ-1387 now

Jacques

De : "Jonathon -- Improov" <[hidden email]>

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

Nicolas Malin (Jira)

[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_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 ?

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

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

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

[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_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) ?

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

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

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

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

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

[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_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

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Nicolas Malin (Jira)

[jira] Closed: (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 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.