Mark Payne created NIFI-12068:
---------------------------------
Summary: Allow documenting specific use cases for processors and
controller services in annotations
Key: NIFI-12068
URL: https://issues.apache.org/jira/browse/NIFI-12068
Project: Apache NiFi
Issue Type: New Feature
Components: Core Framework, Documentation & Website, Extensions
Reporter: Mark Payne
Assignee: Mark Payne
Fix For: 2.latest
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.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
