[
https://issues.apache.org/jira/browse/NIFI-12986?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17839719#comment-17839719
]
Mark Payne commented on NIFI-12986:
-----------------------------------
This PR incorrect marks {{ProcessSession.commit()}} as being deprecated. It is
not deprecated. In the vast majority of cases, {{commitAsync()}} should be
preferred. However, there are still cases where {{commit()}} may make sense. It
is used, for example, in the Site-to-Site server, as it cannot respond to the
client until the commit has completed. Such code *could* be rewritten to use
commitAsync but currently has not. We should not be deprecating methods that we
are actively using and do not necessarily intend to stop using. Additionally,
while it is possible to rewrite in such a way that it uses commitAsync, there's
really no need to, as the synchronous commit is still a valid approach and is
more straight-forward.
Additionally, the PR changes the formatted of the methods from the syntax:
{code:java}
<p>
Documentation Paragraph 1
</p>
</p>
Documentation Paragraph 2
</p> {code}
To a less explicit version of:
{code:java}
Documentation Paragraph 1
<p>
Documentation Paragraph 2 {code}
This should be undone, as the former formatting is preferred and is the
dominant formatting throughout the codebase. It also makes it more clear where
a paragraph begins and ends, and results in more consistent rendering of the
text, as the latter approach does not necessarily apply the same formatting as
the former.
It does look like the commit applies some additional documentation around
Exceptions that are thrown, but honestly it is difficult to say, as Github
shows it as if methods were added and removed, or parameters were changed, etc.
I think it gets confused by the change in formatting?
> Tidy up JavaDoc of ProcessSession
> ---------------------------------
>
> Key: NIFI-12986
> URL: https://issues.apache.org/jira/browse/NIFI-12986
> Project: Apache NiFi
> Issue Type: Sub-task
> Reporter: endzeit
> Assignee: endzeit
> Priority: Major
> Fix For: 2.0.0-M3
>
> Time Spent: 1h 20m
> Remaining Estimate: 0h
>
> While working on NIFI-12982 I noticed that the JavaDoc of {{ProcessSession}}
> has some minor typos and documentation drifts between method overloads.
> The goal of this ticket is to aim make the JavaDoc for the current
> {{ProcessSession}} specification more consistent. The specified contract must
> not be altered.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
