Atom-ide-ui: Code-Highlight instructions unclear without additional explanation (code entry point, CodeActionProvider object, apply() function)

[wooooooooooooooowastaken]

Description

The Readme file describes the services available but the code-highlight instructions aren't clear to me.
Specifically, I would appreciate help on the following items:

1. Where is the package entry point?
2. How do I return a CodeActionProvider object?
3. Where do I place the values for grammarScopes, priority?
4. Where can I find the instructions for creating my apply() function?

Note: I was able to get to the second step before getting stuck (export function provideCodeActions(): CodeActionProvider { return ... } I followed the link regarding types.js but did not find additional instructions to clarify the above. Both code sections of the instructions are copied below.

Thank you for your work on this project!

Version information

• Atom: 1.23.3
• Client OS: Windows 10 Pro, version 1709, OS Build 16299.214
• atom-ide-ui: v0.8.1
  

  Code-highlight instructions

Service API

Provide the code actions Atom service by adding this to your package.json:

"providedServices": {
  "code-actions": {
    "versions": {
      "0.1.0": "provideCodeActions"
    }
  }
}

Then, in your package entry point, add:

export function provideCodeActions(): CodeActionProvider {
  return ...
}

You must return a CodeActionProvider object as described in atom-ide-code-actions/lib/types.js.

• grammarScopes should be a list of scope names of grammars
  that the provider should apply to.
• priority will be used to determine the ordering of code actions in the case
  of multiple providers.
• getCodeActions will be called in the situations described above, with a list
  of intersecting diagnostics. See screenshots above to see how actions are displayed in the UI.
  Once the user clicks an action, your apply() function will be called.

Type.js instructions

/**
 * Copyright (c) 2017-present, Facebook, Inc.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree. An additional grant
 * of patent rights can be found in the PATENTS file in the same directory.
 *
 * @flow
 * @format
 */

export type CodeHighlightProvider = {
  highlight(
    editor: atom$TextEditor,
    bufferPosition: atom$Point,
  ): Promise<?Array<atom$Range>>,
  priority: number,
  grammarScopes: Array<string>,
};

[Goom11]

cc: @hansonw is out of the office for the next two weeks but once he's back he should be able to answer your questions.

In the meanwhile, this may help: https://github.com/facebook/nuclide/tree/master/pkg/nuclide-clang
In lib/main.js, you will find and example of provideCodeActions. You can see here how a CodeActionProvider object is returned. Inside the lib/CodeActions.js file you will see the apply() function. Hopefully this is enough to get started.

This pkg in Nuclide also calls provideCodeActions in lib/main.js: https://github.com/facebook/nuclide/tree/master/pkg/nuclide-refactorizer but overall seems a bit more confusing to me but maybe it will be helpful.

Let me know if you have any other questions :)

[hansonw]

@Goom11's example is a good one. Note how the return value matches the type definition: https://github.com/facebook/nuclide/blob/master/pkg/nuclide-clang/lib/main.js#L195

The apply() function can do anything arbitrary JavaScript code that you desire. It will be called when the user triggers the action.

You may also want to refer to Atom's guide on creating packages: http://flight-manual.atom.io/hacking-atom/sections/package-word-count/