From the KeymapManager docs:

In Atom, you can access a global instance of this object via atom.keymap.

This doesn't seem to be true anymore.

I think it would be helpful to all be on the same page with the API goals before we make any more decisions. Here are the thoughts I have about the API.

TL;DR The API should give people the ability to do what they want, but should not include helper methods.

API Rules

1. The API should only contain classes, methods and events. ¹
2. The API should contain the minimal set of essential interfaces to create a package.
3. Every class, method and event in the API should be well documented using examples where appropriate.
4. Class, method and event names should be be descriptive and unambiguous.
5. Every method and event should have a spec.
6. Exceptions can be made, but they should be rare. ²

API Philosophy

• A smaller API makes it easier it to change Atom. The goal is to create the smallest API possible, but not smaller.
• It is much easier to add to an API than to modify/remove from it. Existing packages will continue to work when an interface is added. Removing or modifying an interface will cause packages to fail and requires a major version bump.
• The API is a contract with package authors. It is our guarantee that we will document, maintain and test the interface we expose. It also implies that we will give appropriate warning when changes to the API will break packages.
• The API is not a helper library, it is the basic interface used to create packages. Users should be able to build helper libraries by combining existing API methods.

Before we freeze the API we need to finalize how it will look. This includes removing methods, updating existing methods and adding methods we may have overlooked.

We can use https://github.com/atom/api/blob/master/api.txt as the focus of our changes. Once we have consensus on the final form we

• Freeze the workspace/workspaceView (#1)
• Freeze the pane/workspaceView (#2)
• Freeze the editor/editorView
• Freeze all other classes
• Freeze the events
• Make sure all API methods and events have specs
• Document all API methods and events have documentation
• Implement changes in the atom/atom code

@probablycorey and I talked today about API doc generation, here are some thoughts from that conversation.

Doc string changes

Essential / Extended

We decided in the meeting to eschew the Public designation in favor of Essential and Extended labels. So something like this:

# Essential: For each selection, replace the selected text with the given text.
#
# text - A {String} representing the text to insert.

API Sections

We really liked the idea of sections or topics of methods. We propose copying the structure of apple's new API docs.

• All methods would be in sections
• All methods would expand to show the method's doc
• All methods would be collapsed on load unless #methodName in the url
• Classes would be on the left side

It might look something like this (envision with atom.io styling):

How to specify the sections in the doc? There are two options. One is to specify the section in the method body itself:

# Essential: Modifying Text: For each selection, replace the selected text with the given text.
#
# text - A {String} representing the text to insert.

Or by grouping methods into the sections in the code, and specifying a sort of section header above that section:

###
Section: Modifying Text
###

I vote for the latter as it will force us to structure methods in a way consistent with the docs, we will repeat less, we can have private methods in the same sections.

Tech

We're using biscotto to generate the metadata, but we need something else to generate the actual doc pages.

We could use ruby to parse the tomdoc, but I think we have enough changes to it (essential, links to other things), that it should be something we control.

I propose we create two new repos (names of these repos can change)

• atom/tomdoc - pull the tomdoc parsing bits out of biscotto and place them into a repo.
• atom/api-generator - coffeescript to consume the metadata and generate a docs site using atom/tomdoc

Let me know what you guys think.

Goals:

• Separation Of View And Model
• Registration Of Autocomplete Providers (AutocompleteRegistry)
• Suggestion Model Object
• Asynchronous Provider API
• Sliding Window For Display / Pruning / Introduction Of Suggestions

Reference: https://discuss.atom.io/t/what-can-we-do-to-improve-autocomplete/13001/19