How did you approach learning the API?


#1

So this is something of a general question for you developers, but of course it is relevant to atom / package development also, especially in the light of the on-going reworking of the API and related docs:

When you first came across Atom and decided to try writing a package or maybe a PR, how did you go about learning what you needed to get started?

As mentioned elsewhere, my developer skills are somewhat… rudimentary. And one thing I noticed is that the explosion of frameworks and APIs, especially in the web development world, does not seem deter experienced developers in the least. It seems to be a distinctive property of your species, to be able to tackle and conquer new APIs with increasing ease and efficiency the more you do it - no matter how difficult that may sometimes be (due to bad documentation for example).

I’m sure there must be many methods out there, which you may have developed over a number of projects, and which help you bring order to the chaos.

So what’s your secret?
What’s your way of getting to know, and quickly applying, the ins and outs of a new API?


Where to begin with contributing?
#2

For me, it really just boils down to:

  1. Read the documentation
  2. Try to write something simple to test my understanding
  3. If the above fails and the project is open source, read the source
  4. Rinse
  5. Repeat

I have an extension that I wrote for Sublime Text that I started porting to Atom, auto-copyright, that I used to learn the ins and outs of the Editor API. (I still haven’t finished it for Atom though … I really need to get that done :laughing:) And some of my other packages, specifically the -indicator ones, white-cursor and red-wavy-underline, were to teach myself how various other CSS and UI customization worked … as well as being useful :grinning:


#3

So do you do that in any structured way, say starting with the most low-level stuff, or starting with the smallest and most obvious methods and classes etc?


#4

For Atom I found the best way was to just start mucking around in the developer tools. Being able to explore and test the API from within Atom is very cool. So, when I wanted to find out how to do something I could just inspect the relevant objects in the console to see what methods are available, write some stuff to test, and see the results immediately.

Reading the source was also a big help - and the source for packages. The core packages are a great resource to see how the ‘proper’ way to accomplish something is.


#5

No, not really. Most application APIs are so interconnected that there really isn’t a good way to restrict yourself. I just pick a spot that seems interesting, start reading there and follow the links. Then again, I was the kid in school that entertained himself by reading the encyclopedia by bouncing from volume to volume, following the references from one article to another.


#6

That’s a good point. That thing has become so powerful these days, people keep discovering new uses and hidden features.


#7

I have found Atom to have surprisingly few layers of code. I often use the inspector (dev tools) and follow execution down into the murky depths.

I also do project wide searches in the Atom project for variables and feature names.

I found it very useful to study the atom-shell docs. They are very interesting. I am tempted to write a little app directly in the shell.


#8

This is something I haven’t gotten around to yet. One of the crazy ideas I have for atom-shell is to write an email/calendaring program. But to call that a “huge undertaking” would be an understatement :laughing:


#9

One advantage of reading up on the shell is understanding the directory structure in Atom. Then I can ignore a lot of Atom code when studying it.


#10

I also found the developer tools very useful - from a web dev background anyway, I am familiar with the Chrome dev tools.

I started by opening console and typing “atom”, “atom.getWorkspaceView” etc to see how it was structured etc and see real time data (and try to change values etc).

Then when I needed specifics I just did a search in the API for the specified class.


#11

This is an interesting topic. I’d love to have more opinions on this, as it could really shape the way we structure the docs.

I’m almost entirely a task-based learner when it comes to writing code. I suppose the opposite of @leedohm. I want to do a thing, and I’ll stumble around until I accomplish that thing. The stumbling usually consists of finding something else similar, and modifying it, or using its technique as a jumping off point into some docs.

I definitely was like that with atom at first. I want to put something in a tab, look at settings-view. I want that thing to use the git integration, look at git-diff, etc.

I tinker with an ios app in my free time, and apple’s API has an insane surface area. The only way I can navigate it is to find an example, then use the example’s approach as a starting point in the docs. For example, I want to put data in a scrollable list like every app ever. How?! FUUUU there is no ListView! Find example that has data in a list, notice it uses a UITableView, look up UITableView, and learn about UITableViewDataSource. Then go back to searching for examples using UITableViewDataSource to understand the general usage patterns.

The approach I want to take for the new docs organization follows the way I’ve been learning iOS stuff. At the top level would be snippets / recipes / common usage patterns that are task-based. Like ‘register a command’, ‘get all the editors’, ‘open your own content in a tab’, etc. Really common stuff. These show you how to accomplish that task, then can give you pointers into the guides, the API docs, and example packages that use said pattern. Additionally, we’re splitting the API into Essential and Extended. Where ‘Essential’ APIs are those that you will very very likely need to use when you start writing an atom package. If you need to dig deeper or do something crazy, the Extended APIs will be there when you’re ready. Hopefully we’ll still have it organized well enough that folks like @leedohm can read it like a book!

Thoughts on the approach?


#12

@benogle That makes a lot of sense to me. As you know I’m always asking for a bunch of examples with new API changes etc, in order to help people familiarize themselves with that new thing and create an “Ah, I see!”-based access road into it.
Snippets and quick tutorials of the “How do I…” kind are IMHO the best way to accomplish that.

In other words, the API should practically offer itself as the solution to “that thing I want to do”, by falling into place intuitively as soon as someone sees it implemented.

Obviously, I wouldn’t be able to offer any specific advise on this, as to how to approach specific methods and classes etc, I’m more of a big picture kind of guy I suppose. But I think the recent changes with your event emitters look like a nice exercise in simplification, and should serve this purpose well.

Edit:

I was conflicted on the renaming of events to the “onDid” pattern, because it sounds a bit clunky, language-wise. But here again, we have a recognizable pattern that practically offers itself to someone who has just seen one or two examples, to the point where one could sometimes just guess at the right event name to use in some cases.


#13

I have a bad habit of reading source first and reading docs last. I’ll read the source for a project that seems similar in some way, observe how they do it, go off and try to do whatever I was after, fail hard, and then at that point go and read some docs. I would probably read the docs first if they were generally (speaking of all projects, not atom) more rich in examples. As an example, whenever I browse the node docs, I find myself subconsciously scrolling to the entries that are the most fleshed out with examples and descriptions. They might not even be what I was after, but it’s just easier to get oriented with examples.

Also I find it’s easier to stay productive the longer I look at mostly code … the more I read plain english the more my brain slips into the hazy forgetfulness of everyday life …

One thing I miss from emacs is all the options for interactive self-documentation. Things like apropos mode, the different describe- commands linking to docstrings, etc … the keybinding resolver and being able to inspect objects in the console are great steps in this direction, but sometimes I really miss the extensiveness of its help system.

Are there any projects working on a similar interactive help system for atom? Or perhaps any built-in functionality I’ve overlooked?

On the layout of the docs … I don’t think the current structure is so bad. Raw API docs, intro-level guides, and advanced how-to guides make for a really natural learning style. I think those action-oriented docs like “how to put my own content in a tab” would great content for the Advanced Guides section.


#14

They aren’t. Obviously they have helped a lot of people create some great packages, submit PRs or just hack their own setup.
But of course everything can be optimized and improved and it’s nice to see where that is currently going.


#15

Noted. And I am totally with you. I learn like that as well.

No. The API docs are now available as a ball of json: https://github.com/atom/atom/releases/download/v0.126.0/atom-api.json So the data is there for some package to read and insert hints or something while developing.

I’m convinced that the parts that hit atom’s API of most packages is lifted from other packages. Our previous API docs were horrible, and not even true in many cases. The current guides are pretty limited. I think updated docs are a big part of making atom more accessible.


#16

Off-Topic (sort of). Am I mistaken or is “API” an incorrect term for Atom? Aren’t all the calls in Atom to internal objects and methods? When I think of an API I think of a strict list of methods that are independent of the internals, usually implemented as a separate layer of code.


#17

No doubt. Judging from what people discuss here, it is the examples from other packages that were most helpful, even though they did also consult the docs to understand specific methods and classes, usually after seeing them in other people’s code.


#18

Same same IMO. And technically, it is an Application Programming Interface. The public API is really a contract with users that we will not change things without explicit deprecation and notification. Basically: “you can rely on us not breaking things when you use these methods”. Use private stuff, and we will likely break your packages.


#19

This hasn’t been defined yet, right? I’m calling whatever I can find.


#20

It certainly is in flux right now, but it has been defined. Everything here is public: https://atom.io/docs/api/latest Anything you find that isnt in those API docs is private.