[
https://issues.apache.org/jira/browse/NIFI-12068?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17768104#comment-17768104
]
Joe Witt commented on NIFI-12068:
---------------------------------
Experimenting with this locally but looks really good. We'll have a lot more
use cases and such to write but this serves as a great foundation. Will merge
soon
> 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
> Priority: Major
> Fix For: 2.latest
>
> Time Spent: 10m
> Remaining Estimate: 0h
>
> 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)
