Bugzilla – Full Text Bug Listing
| Summary: | Re-work context help binding feature | ||
|---|---|---|---|
| Product: | z_Archived | Reporter: | Konstantin Komissarchik <konstantin> |
| Component: | Sapphire | Assignee: | Ling Hao <ling.hao> |
| Status: | CLOSED FIXED | QA Contact: | |
| Severity: | enhancement | ||
| Priority: | P3 | Keywords: | plan |
| Version: | unspecified | ||
| Target Milestone: | --- | ||
| Hardware: | All | ||
| OS: | All | ||
| Whiteboard: | |||
|
Description
Konstantin Komissarchik
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. |