Details
-
New Feature
-
Status: Resolved
-
Major
-
Resolution: Fixed
-
None
-
None
Description
Currently, extensions have the ability to document their purpose using the `@CapabilityDescription` annotation. This is very helpful but is insufficient. Some processor have a Capability Description that is 1-2 sentences. Others have multiple paragraphs.
Some components are able to achieve many different use cases while other components perform a very specific use case.
Some components are designed to be used together in order to accomplish a particular use case.
We need a way to very clearly and succinctly document how to achieve different use cases with our extension points. And do so in a way that is consistent.
Most importantly, we need a way to very easily and clearly document how to achieve specific use cases. We've largely built our documentation around "Here's what this component does." And that is important if you want to understand the component itself. But dataflow designers do not need to know all of the details of how a particular component works. Those building dataflows mostly need to know "Here is a use case that can be accomplished with this component. Here's how to do it."
In order to achieve this, some extensions have additionalDetails.html written. And while this is great for complex illustrations including images, etc. it is a lot of work to put together. Additionally, it is entirely divorced from the code, so it can become stale more easily, and there's no way programmatically to know that the information exists or to harness it.
To address all of the above concerns, we should introduce a couple of new annotations:
@UseCase to describe a specific use case that can be accomplished by a particular extension, to include a very brief (1-2 sentence) description, (separately) any additional notes that are needed, some keywords for the use case, how to configure the component to accomplish this use case, etc.
@MultiProcessorUseCase to provide the same sorts of details about use cases that include not only a single Processor but multiple Processors. For example, ListS3 -> FetchS3Object as a single use case. IdentifyMimeType -> CompressContent as a single use case, etc.
The scope of this Jira is to introduce such interfaces, update the HtmlDocumentationWriter to write out the use case docs in the documentation, the XmlDocumentationWriter to write out the use case docs in the manifests, and to update a handful of components to use these annotations in order to make it clear how they are intended to use.
Out of scope of this Jira:
- Updating all processors to use these annotations. This will happen over time
- Annotation all use cases for the Processors that are annotated. This will happen over time and new use cases will come up in the future
- Updates to the UI (aside from the generated documentation). We will not update the UI in this ticket, but it may be helpful in the future, to provide these details when choosing a Processor, Controller Service, etc. to add to the canvas.
Attachments
Attachments
Issue Links
- links to
