[Moose-dev] Re: [Better Comment Initiative]: MooseEntity

Doru the key difference with stringHolder is that in StringHolder nobody understand how it works. Because it I would know I would go way faster. So I suggest that we spend next two weeks not typing code on moose but only fixing comments and we will get a real impact. For pharo I have always to reverse engineer (network, filesystem...) because people forget that a soft is finihsed with it is really documented. We have: ------- MooseEntity is an abstract entity. Entities should subclass this class. The state instance variable provides a mechanism for extending the state of entities. Proposition: ---------- MooseEntity is an abstract class that refines MooseElement. Model entities should be instances of subclasses this class. MooseEntity provides means to add state for model extensions as well as meta information. The state extension is provided through MooseEntityState (see MooseEntityState). Using this mechanism, a package can extend an entity to add more state. This extension will only be visible when the package is loaded. Property Extension ---------------- Any MooseEntity can extended with property that is described using the FAME meta model as follow: YourEntity>>yourExtendingAttribute <MSEProperty: #yourExtendingAttribute type: #YourType> ^ self privateState attributeAt: #yourExtendingAttribute YourEntity>>yourExtendingAttribute: aValue <MSEProperty: #yourExtendingAttribute type: #YourType> ^ self privateState attributeAt: #yourExtendingAttribute put: aValue Note that a nice helper, lookUpPropertyNamed: omputedAs: is provided to hide the use of privateState to subclasses. Old versions used <property:longName:description:> as in the following example. FAMIXAttribute>>hierarchyNestingLevel <property: #AHNL longName: 'Attribute hierarchy nesting level' description: 'The hierarchy nesting level of an attribute.'> ^self lookUpPropertyNamed: #AHNL computedAs: [self belongsTo hierarchyNestingLevel] Entity Navigation -------------- In addition, any MooseEntity can also be annotated with navigation declarations (which are used by the user interface to propose navigation options to the user). For example, the class FAMIXClass can define the navigation 'Accessor Methods' as follows FAMIXClass>>accessorMethodsGroup <navigation: 'Accessor methods'> ^ FAMIXMethodGroup withAll: (self accessorMethods) withDescription: 'Pure accessors in ', self name The pragma <navigation:> declares that the method accessorMethodsGroup is the method to invoke to get the associated navigation. The method navigationSelectors (see below) returns the list of methods declaring navigation of a given MooseEntity. Property ------- Finally, MooseEntity provides the possibility to add other free style properties (we call properties to avoid clash name with Java annotations), to any moose model element. For example, a new information can be added to any model entity and it should be accessible. Like for example a comment. Note that such a solution does not use FAME based description and as such will not appear when we will query the declared properties. propertyNamed: name propertyNamed: name put: value Have a look at the test testProperty for an example of property use. Some API: mooseDescription returns the description (FAME instance) described the receiver. mooseDisplayString returns a name for UI use. allDeclaredProperties returns the properties (FAME instances) that describe the receiver. This method seems to be obsolete. But its subtitute is unclear. allPropertySelectors Return a dictionary with all properties of the entity, including metamodel properties, metrics, and navigation groups. Keys are abstract names of properties, values are implementing selectors. for example: #ATFD -> #numberOfAccessesToForeignData means that ATDF is computed by invoking the method #numberOfAccessesToForeignData. This method seems to be obsolete, but its replacement is unclear. The previous comment is now published. Open Questions. ----------- 1 lookUpPropertyNamed: #yourExtendingAttribute computedAs: I started to deprecate lookUpPropertyNamed: #yourExtendingAttribute computedAs: but I do not think that we want all the FAMIXsubclasses to know that there is a private state I prefer self lookUpPropertyNamed: #yourExtendingAttribute computedAs: self privateState attributeAt: #yourExtendingAttribute put: aValue So can we agree on this before I rewrite everything? 2 allDeclaredProperties return the properties (FAME instances) that describe the receiver. The properties are defined using <property:longName:description:>. This is an obsolete method. But it is used by the system and even is part of the public interface of hismo. How do we know the declaredProperties then? 3 about description? Is it obsolete? because it is used what is the relationship with mooseDescription? MooseEntity>>description ^self privateState description 4 allPropertySelectors Return a dictionary with all properties of the entity, including metamodel properties, metrics, and navigation groups. Keys are abstract names of properties, values are implementing selectors. for example: #ATFD -> #numberOfAccessesToForeignData means that ATDF is computed by invoking the method #numberOfAccessesToForeignData. This is an obsolete method. so basically you and me (but I do not have the knowledge and the time) and we should not think that new engineers can do anything at this level because there is no magic, no doc generate less knowledge and less knowledge less doc. so what do we do: Plan A- build a roadmap and do it (I can probably work every two evenings on it for a month). Right now (this evening we log on chat and we fix) these two allPropertySelectors is used allDeclaredProperties is used Plan B - I focus only on pharo (because I cannot do both especially right now). so if somebody with knowledge wants to join I will give a try. Stef