--- On Sat, 7/31/10, Scott Gray <[email protected]> wrote: > Yeah whoops, thanks for fixing that > up. > > Inline > > Regards > Scott > > On 1/08/2010, at 3:55 AM, Adrian Crum wrote: > > > Scott, > > > > I fixed the code and built it out a little. > > > > This is a good idea, but I have a couple of problems > with it: > > > > 1. User-oriented meta-data should be kept in > properties files - so it can be internationalized. The > drawback to that is, developers will be less likely to > include descriptions if they have to do it in a separate > file. > > It wasn't my intention for the meta-data to be oriented > towards the user, I see it as developer documentation > only. A few times in the past I've noticed it can be > difficult to describe an attributes purpose from the service > description and inlining them was intended to make it a > little more like a javadoc.
By user I meant developer. If it's developer information only, then why store it in the model? A developer could just look at the service definition file. > > 2. Description text should not be stored in the model > - it increases the model's memory footprint greatly. > Instead, the descriptions should be retrieved from > properties files when needed (in AvailableServices.groovy, > for example). > > Well I agree with you except for the properties file part, > but I guess that comes back to #1 above. We could > always look at doing some sort of lazy loading, where the > descriptions are only added to the model if they're > requested. Considering that viewing the service in > webtools is the only way to expose the descriptions, you'd > probably never end up with more than a few dozen actually > loaded into memory. The reason I suggested the properties file is because this issue came up before with the entity field descriptions. At the time those were being added, there was interest in internationalizing them. From my perspective, using a properties file is easier than the existing implementation. In the AvailableServices.groovy script, concatenate the service name and attribute name, then use that as a key to look up the description in a properties file. No need to add anything to the model. > > > > -Adrian > > > > > > --- On Sat, 7/31/10, Adrian Crum <[email protected]> > wrote: > >> Scott, > >> > >> Are you sure this does what you intended? The > parameters > >> are being assigned the service's description, not > the > >> parameter's description. > >> > >> -Adrian > >> > >> --- On Sat, 7/31/10, [email protected] > >> <[email protected]> > >> wrote: > >> > >>> From: [email protected] > >> <[email protected]> > >>> Subject: svn commit: r981018 - in > >> /ofbiz/trunk/framework/service: dtd/services.xsd > >> src/org/ofbiz/service/ModelParam.java > >> src/org/ofbiz/service/ModelServiceReader.java > >>> To: [email protected] > >>> Date: Saturday, July 31, 2010, 1:26 AM > >>> Author: lektran > >>> Date: Sat Jul 31 08:26:42 2010 > >>> New Revision: 981018 > >>> > >>> URL: http://svn.apache.org/viewvc?rev=981018&view=rev > >>> Log: > >>> Add a description element for service > attributes, > >> should > >>> make documenting some services a little > easier. > >> Still > >>> need to display it in webtools somewhere. > >>> > >>> Modified: > >>> > >>> > ofbiz/trunk/framework/service/dtd/services.xsd > >>> > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java > >>> > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java > >>> > >>> Modified: > >> ofbiz/trunk/framework/service/dtd/services.xsd > >>> URL: > >>> http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/dtd/services.xsd?rev=981018&r1=981017&r2=981018&view=diff > >>> > >> > ============================================================================== > >>> --- > ofbiz/trunk/framework/service/dtd/services.xsd > >>> (original) > >>> +++ > ofbiz/trunk/framework/service/dtd/services.xsd Sat > >> Jul > >>> 31 08:26:42 2010 > >>> @@ -314,6 +314,7 @@ under the License. > >>> > >>> <xs:complexType> > >>> > >>> <xs:sequence> > >>> > > >>> <xs:element minOccurs="0" > >>> maxOccurs="unbounded" > ref="type-validate"/> > >>> + > > >>> <xs:element minOccurs="0" ref="description" > /> > >>> > >>> </xs:sequence> > >>> > >>> <xs:attributeGroup > >>> ref="attlist.attribute"/> > >>> > >>> </xs:complexType> > >>> > >>> Modified: > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java > >>> URL: > >>> http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java?rev=981018&r1=981017&r2=981018&view=diff > >>> > >> > ============================================================================== > >>> --- > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java > >>> (original) > >>> +++ > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java > >>> Sat Jul 31 08:26:42 2010 > >>> @@ -43,6 +43,9 @@ public class ModelParam > implements > >> Seria > >>> /** Parameter name */ > >>> public String name; > >>> > >>> + /** The description of this > parameter */ > >>> + public String description; > >>> + > >>> /** Paramater type */ > >>> public String type; > >>> > >>> @@ -88,6 +91,7 @@ public class ModelParam > implements > >> Seria > >>> > >>> public > ModelParam(ModelParam > >>> param) { > >>> this.name = > >>> param.name; > >>> + this.description > = > >>> param.description; > >>> this.type = > >>> param.type; > >>> this.mode = > >>> param.mode; > >>> > this.formLabel = > >>> param.formLabel; > >>> > >>> Modified: > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java > >>> URL: > >>> http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java?rev=981018&r1=981017&r2=981018&view=diff > >>> > >> > ============================================================================== > >>> --- > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java > >>> (original) > >>> +++ > >>> > >> > ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java > >>> Sat Jul 31 08:26:42 2010 > >>> @@ -518,6 +518,7 @@ public class > ModelServiceReader > >>> implemen > >>> > >>> ModelParam param = new > ModelParam(); > >>> > >>> > >>> param.name = > >>> > >> > UtilXml.checkEmpty(attribute.getAttribute("name")).intern(); > >>> + > > >>> param.description = getCDATADef(baseElement, > >>> "description"); > >>> > >>> param.type = > >>> > >> > UtilXml.checkEmpty(attribute.getAttribute("type")).intern(); > >>> > >>> param.mode = > >>> > >> > UtilXml.checkEmpty(attribute.getAttribute("mode")).intern(); > >>> > >>> param.entityName = > >>> > >> > UtilXml.checkEmpty(attribute.getAttribute("entity-name")).intern(); > >>> > >>> > >>> > >> > >> > >> > >> > > > > > > > >
