Community
Participate
Working Groups
The current implementation of the context help binding feature relies on a naming convention. The UI generation code creates a help context id for each property editor based on a combination of model element type name and property name. The model author is then responsible for making sure that there is a matching help context binding with content association for a given property. This approach works ok, but has the following problems: 1. It is a pain to maintain the external help content file. It is hard to write those context ids by hand without making mistakes and the help content can silently get detached if model is refactored. 2. Higher-order behaviors are not feasible. For instance, in some cases, it is better to write help content at the level of a model element rather than at the level of a property. Additionally, when a property is defined in an inherited model element type, it should be possible to either re-use help content for a property across all sub-types or to specify different help content for the property in each of the sub-types. My current thinking on this is that the help content association should be done with an annotation rather than maintaining an external help file. This assumes that we can figure out how to write a custom help provider.
For permanent record... Ling has created a prototype which includes @HelpContent annotation that takes a string. The prototype proves that we are able to inject arbitrary content into Eclipse help system. The next steps: 1. For title, you want property.getLabel( true, CapitalizationType.TITLE_STYLE, false ) 2. Extend the annotation to support links to external resources. 3. Explore the limits of styling in the help system. We’d like to support at least some rudimentary styling instructions. At least paragraphs, but ideally bold/italic and lists too. 4. Define search strategy. If content not found, should probably search containing type (implies HelpContent annotation on elements, not just properties) and then parent property, etc. 5. Define a content merging strategy. Consider property that overrides one from base class. It would be good to allow both complete override of help content as well as augmentation. Similarly, it may be useful to allow augmentation of element’s help content. This would need to be controlled via switch(es) on the annotation. 6. Integrate with Sapphire’s localization system. There are two parts that need to change: ExternalizeStringResourcesProcessor and the runtime retrieval side. Reference how labels are handled. 7. Define a way to provide a programmatic help content provider. Like we have DefaultValue and DefaultValueProvider…. HelpContent and HelpContentProvider. The implementation of HelpContent should use the same underlying API that a developer would implement with HelpContentProvider to make sure that the provider interface is at least as expressive as the static version. 8. Augment help content with generated information retrieved from property annotations. Default value, min and max come to mind. There may be other. Take a pass through annotations and make an evaluation of which ones we want to expose via help. 9. Same capability in sdef files. 10. Write a tool for moving existing code to the new annotation. Way too much of it in existing models to do it all by hand. 11. Rip out existing support for help context id.
Several review comments: 1. The help content lines introduced from annotations (default, min, max, etc.) should be at the very end of the presented help content, not at the beginning. 2. I also expected inherited content to come first, followed by more specific content. In this case, it would probably be worth it to split AUGMENT merge strategy into two: PREPEND and APPEND. I can see both cases being useful.
A few more comments based on playing around with this feature. 1. I think the terminology used needs a little work. I should have caught that earlier, but it looks like "documentation" rather than "help" is the more prevalent term in similar contexts... javadoc, doc comments, etc. I think "help" is the system that is used to display "documentation". Here is what I am thinking for renamings: HelpContent -> Documentation HelpContentData -> DocumentationData HelpContentMergeStrategy -> DocumentationMergeStrategy HelpContentProvider -> DocumentationProvider HelpContentProviderImpl -> DocumentationProviderImpl Similar changes should be made in the sdef schema and model. Also looking at the HelpContent/Documentation annotation, some shortening of of internals could be applied without loosing any meaning... RelatedTopic -> Topic relatedTopics() -> topics() 2. The case transform is not applied to the topic label. A title case transform seems appropriate for that case.
From Ling Hao: -------------- Content search and merge strategy summery: Prepends or appends parent property's documentation as specified in document's DocumentationMergeStrategy. Search stops when the property's merge strategy is REPLACE. Append property element's documentation content (if exists) Append generated information about the property. Currently we display default,min, max, non-null, and read-only.
Hit a new problem. After recent changes to support formatting annotations in doc content, the new line between generated information statements has been lost. You can see this on any property that has multiple generated statements.
Marking as fixed.
Verified via gallery sample (Help node in the content outline).
Meant to close.
