Bug 540685 - Document which Job#create method to prefer - ICoreRunnable or IJobFunction
Summary: Document which Job#create method to prefer - ICoreRunnable or IJobFunction
Status: RESOLVED FIXED
Alias: None
Product: Platform
Classification: Eclipse Project
Component: Runtime (show other bugs)
Version: 4.10   Edit
Hardware: All All
: P3 enhancement (vote)
Target Milestone: 4.18 M1   Edit
Assignee: Lars Vogel CLA
QA Contact:
URL:
Whiteboard:
Keywords: api, Documentation
Depends on:
Blocks:
 
Reported: 2018-11-01 06:00 EDT by Lars Vogel CLA
Modified: 2020-09-09 03:11 EDT (History)
4 users (show)

See Also:

Attachments
Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Lars Vogel CLA 2018-11-01 06:00:21 EDT 
Looking at the Jobs#create Javadoc it is unclear which method should be used:

public static Job create(String name, final IJobFunction function) 
public static Job create(String name, final ICoreRunnable runnable)

I suggest we add some Javadoc which method to use them.
Comment 1 Lars Vogel CLA 2018-11-01 06:03:49 EDT 
Mikael, could you help here with a Gerrit for the Javadoc? 

I forgot which method we prefer. ;-)
Comment 2 Lars Vogel CLA 2018-11-01 06:30:38 EDT 
Looking at the ICoreRunnable Javadoc I think create(String name, final ICoreRunnable runnable) is the "better" API, as I do not have to call done on the ProgressMonitor and it accepts null as ProgressMonitor.

@Mikael, do you agree? In this case I can add, "Prefer using create(String name, final ICoreRunnable runnable)" to the Javadoc of create(String name, final IJobFunction function)
Comment 3 Lars Vogel CLA 2019-02-19 03:32:11 EST 
Mass change, please reset target if you still planning to fix this for 4.11.
Comment 4 Mikaël Barbero CLA 2019-06-07 09:53:51 EDT 
(In reply to Lars Vogel from comment #2)
> Looking at the ICoreRunnable Javadoc I think create(String name, final
> ICoreRunnable runnable) is the "better" API, as I do not have to call done
> on the ProgressMonitor and it accepts null as ProgressMonitor.
> 
> @Mikael, do you agree? In this case I can add, "Prefer using create(String
> name, final ICoreRunnable runnable)" to the Javadoc of create(String name,
> final IJobFunction function)

+1. It also have the advantage of relying on Exceptions (OperationCanceledException in this case, as reported by SubMonitor.split()) which is much easier than if (pm.isCanceled) { return Status.CANCELED_STATUS; }

Feel free to add me as reviewer of a patch.
Comment 5 Eclipse Genie CLA 2020-09-08 10:20:58 EDT 
New Gerrit change created: https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169012
Comment 6 Eclipse Genie CLA 2020-09-08 10:21:00 EDT 
New Gerrit change created: https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169013