search

APSIMInitiative / ApsimX

ApsimX is the next generation of APSIM
http://www.apsim.info
Other
134 stars 162 forks source link

Remove Description tag for all code #5456

Open hut104 opened 4 years ago

hut104 commented 4 years ago

Use the summary tag in its place

hol430 commented 4 years ago

Thinking about this one some more, I'm not sure if this is what we want. The summary tag is used by the IDE for intellisense descriptions. The description attribute is used by apsim as the variable name in the property presenter. We don't really want complete sentence(s) showing up in the variable name column in apsim's intellisense, but we also want good descriptions in the intellisense in the IDE. So these two pieces of metadata really serve different purposes.

Perhaps what's needed here is

  1. In cases where you have exactly the same text in the description attribute and summary tag, the summary tag should be updated to actually have a summary, rather than a variable name
  2. Rename DescriptionAttribute to VariableNameAttribute or similar?
  3. Document this in the contributing section on the website
hol353 commented 4 years ago

Yep ok this makes sense. Instead of VariableNameAttribute, how about UIDescription (or GUIDescription). This is more descriptive about what it is used for.

hol430 commented 4 years ago

The problem with the current name is that it implies that the attribute describes the variable, which it doesn't really - it just provides a more user-friendly name for the variable. UIDescription or GUIDescription (would have to be GuiDescription to be compliant with our naming standards) still has the same issue.

hol353 commented 4 years ago

I don't understand what you're getting at. UIDescription does describe the variable for the user in the user interface. In the property presenter the user sees descriptions not variable names and so I don't think [VariableName] is right.

hol430 commented 4 years ago

What I mean is that the [Description] attribute doesn't really describe the variable. It contains a user-readable name of the variable. However the name Description implies the opposite.