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