How can we help you write packages?


#8

In my experience it’s not unusual for beta software to have minimal or no documentation, so my comments were made in light of that.

Of course your experience might be different to mine.


#9

Resources

Both were quick and easy enough, and covered what I needed them to.

Documentation

I found it good for learning the basics, but pretty short. Some examples showing how to write a few types of commands would be useful, e.g. text manipulation, navigation/scrolling, creating a custom pane. Also cmd-. should definitely be mentioned in the keymaps guide.

API Reference

Nicely presented, but as others have largely covered, several big omissions:

  • A structural overview, ideally as a diagram or two.

  • Events. Both a list of core events, and the Event class itself. The latter is particularly important for custom editing commands, because it seems the most reliable way to get the “current” editor is off the event (event.targetView().editor), not getActiveEditor() which doesn’t return mini editors, or text entries in non-editor panes. (I’ve never seen this mentioned anywhere - am I wrong?)

  • The Editor reference is missing many useful methods. From the documentation I was convinced I had to get a buffer object (using the undocumented editor.buffer reference?) to do anything but the simplest text manipulation. Turns out many buffer methods are on editor too.

  • How to get from a view to the underlying model. I’ve found stuff squirreled away in the jquery data() store of nodes, but as it’s not documented it feels dirty. Would be nice if this was part of the API.

Finally as a hopeful Emacs convert, one thing I really miss is documentation built into the editor itself. If we were to establish some conventions (e.g., perhaps a “doc” property of a function is its documentation), a whole host of useful documentation tools could be built by anyone. Could also make it easier to spot missing documentation.

Open Source Packages

I’ve learned a lot from vim-mode, and have started snooping through Atom.app to grok some core stuff.

Most Important Thing

The reference issues above.


#10

When I was writing syntax-settings I relied extensively on the documentation and this wonderful site. Here are my thoughts:

  1. Generate package command - works wonderfully
  2. Documentation was really good. I think there is a need for some more on how to set up default settings for your package, but I found what I needed.
  3. Reference was good for my needs. Somewhat confusing at this point to find the exact hierarchy of all the classes but a great start.
  4. Not really!
  5. Events and how to subscribe to them. I could not find much at all on this and what I did find all related to Views (which I haven’t used yet). I really wanted to capture some of the events (eg. ‘save’) but everything broke as soon as I tried.

Edit: I recently noticed all the events in the TextBuffer docs. Yay!


#11

I can’t say the documentation didn’t help me, but in practice I spent more time digging in the sources of atom and open source packages than browsing the documentation.

For instance, regarding buffer markers, while the Marker class is documented, the DisplayBufferMarker class isn’t. But if you have to visually display these markers, you’ll have to rely on DisplayBufferMarker and the editor methods, so I add to dig in the find-and-replace package to understand how these methods worked (fortunately, browsing Atom.app gives access to these classes).

There’s also a lot of classes for which documentation doesn’t list the available events, I had to search all emit instances in the code to find which events a class emit.

But as previously said, this is a beta and I didn’t expected a proper documentation in the first place.

Maybe it could be good to have some kind guidelines on how structure packages classes, For atom-color-highlight I tried to follow the structure of native packages such find-and-replace or bracket-matchers to handle properly views/buffer/markers lifecycle, but I noticed that a lot of similar packages didn’t bother with that, often relying on generated markup instead of buffer markers, what is the best course of action in that case ?
Maybe the Atom team could brief us a bit on what should and shouldn’t be done when trying to works with buffer and grammar (see this topic for instance)

My 2 cents


#12

Resources

Pretty much what @oggy said.

API Reference

  • I’m new to coffeescript. In fact, Atom made me use coffeescript, and the API reference helped me a lot. So far I’m having fun poking around the API reference. But, there are things that can be improved on.
  • The API Reference is pretty sparse on descriptions and examples, but so far I get by by using console.log
  • At this point, console.log is an invaluable tool for discovering hidden features, ie. retainSelection
  • It seems that there are many ways to do things, like for instance, getting the active editor. The alternatives should be documented together.

Open Source Packages

I looked at vim-mode to help me get started. I also find block-travel interesting.

Most Importantly

There must be a way to depend on other apm packages without. I’m not sure if there is such feature, but if there is, it’s not so obvious. I also heard from someone in irc that you can depend on another apm package as long as it is in npm, which is not so ideal since npm is not specifically for atom.

This is important for me because I saw some packages that can be used in my package. In my package, I can also see some features that can be split into a different package. For instance, atomic-emacs can make good use of block-travel, and in atomic-emacs it is possible to split the “sticky selection” feature into another package.


#13

Resources:

These are the places I look for information while I’m hacking, roughly in order:

  1. The official API reference. I usually keep a tab open here while I’m working as a quick reference.
  2. Open-source packages, both the official GitHub ones and otherwise. I’ll often hunt down the implementation of a specific feature I want to emulate by trying to see how someone else already did it. It’s also a good way to track down support libraries that already exist; this is how I found out about Emissary, for example.
  3. The Javascript source in /Applications/Atom.app, especially for Editor and EditorView internals, undocumented methods, and so on. Most recently I’ve been tracing through EditorView to figure out the best way to persistently attach a CSS class to certain .line elements, for example.

I will say that the built-in “Create a package” command is excellent for bootstrapping plugins, although I was surprised that it didn’t create the package in dev/.

Documentation:

I read through the package creation tutorial when I was first getting started, but I haven’t had cause to revisit it much since then. It’s a decent introduction to the major classes in the API and the mechanics of development and publishing, but it’s not really comprehensive.

What would be interesting are a set of follow-on articles for specific topics: event broadcast and subscription, text buffer operations, plugin architecture, writing specs for Views…

API Reference:

As I mentioned, this is the first place I look when I’m hunting for the way to accomplish something specific. It’s a good start, but it is missing some key bits (@abe mentioned the missing DisplayBufferMarker class, for example).

I’ll echo some others that event documentation is probably the biggest omission: what events are broadcast when.

Open-source packages:

Yes, I’ve referred to a bunch of the open-source packages for guidance. I hunted down how to write view specs from vim-mode, I think.

The most important thing

Keep adding content to the API documentation; keep providing high-quality examples. Make sure that API stability is made clear, moving forward.

Overall, I’ve been having a lot of fun hacking on Atom, and I’m looking forward to seeing where it goes in the future. :grinning:

@ProbablyCorey: By the way, what’s the best channel for requesting additions to the API? The feedback button, topics here… ?


Where to begin with contributing?
#14

@smashwilson the packages category on this forum is the best place to post API requests, or problems you noticed with the API.


#15

This topic is now pinned. It will appear at the top of its category until it is either unpinned by a moderator, or the Clear Pin button is pressed.


#16

The biggest issue I’ve faced is not knowing what events I can subscribe to and what calls them. A lot of the time it’s trail and error.


#17

+1 on docs for events - hunting around in the inspector can suffice for now, but there’s lots of trial and error.


#18

In-house grammar documentation instead of referring to the TextMate manual, particularly with stuff where it’s unclear what Atom does or doesn’t explicitly support like recursive grammars, referencing other grammars, and so on.


#19

I would love to see a way to write packages without being forced to write it in coffee-script. I personally dislike coffee-script and believe it hinders me for performing otherwise mundane tasks. Others love it. Both oppinions is fine, and both exists - why not allow both?


#20

Both are allowed. There is some question around how well supported writing extensions in JavaScript are because of complications around extending the View class … but both are possible to my understanding.


#21

I see. I did not know that. I guess some richer documentation and examples for javascript packages would be helpful. At the very lease divulge its existence. :slight_smile:


#22

You mean like this? Re: divulging its existence

Just added a link to this answer in the FAQ.


#23

Another thing I think could really help packages developpers is some kind of isolation mode in atom where you can run Atom with only the current package and the ones it depends upon.

The isolation should only concerns packages in the ~/.atom/packages and ~/.atom/dev/packages directories (integrated packages should always be available to avoid having an unusable editor in that mode).

In that context, packages should declares if they rely on the presence of another package(s), maybe through a package.json config.

The isolation mode could be launched with something like atom --isolate.

It will also be useful to spot which package cause some unexpected behaviors, with dozens of packages finding the culprit is quite the task. And AFAIK there’s no easy way to do that now.

What do you think ? Some issues I haven’t foreseen ?


#24
  1. I just did a package and I constantly went through the code of Editor, EditorView and TextBuffer. There are a lot of undocumented functions that I could only learn of from there (like Editor::getBuffer which is super-useful).

  2. It would be useful if the API could have a function that returns all the viewable ranges on the screen (either fully or partially). I hacked that through my code and I consider it useful when making packages that only care about what’s visible.


#25

+1 on the API being impossible to find. I couldn’t see a link from the Documentation page, where I would have expected. I ended up doing most of my development by reading other package’s source code and inspecting stuff in the Developer Tools :worried:


#26

I like the promise of atom but so far I’m not finding the plugin development experience much fun.

For starters, there is no debugger, at the very least show me the exception somewhere more useful than the log. console.log is not a debugger.

A way to reload packages is needed. At the moment, for instance, I’m trying to debug a problem with the serialization so dev mode is useless.

A coffee script primer for application developers would also be nice.


#27

Debugging is available via the Developer Tools, which can be activated via alt-cmd-I. Debugging is baked in just like in any Chromium. Go to the Sources tab, and add as many breakpoints as you want.

Reloading has been supported for a long, long time; simply press ctrl-alt-cmd-L, or click the menu item aptly named Reload (located under View).

As for documentation, what more do you need/want besides e.g. these?

There are many good tutorials and what not on CoffeeScript out there.