Documentation for native UI elements


#1

I’ve been developing for atom for 3+ years now. The APIs are always changing as the team continues to grow the editor and that is great. The problem is there are aspects of atom that are important for non-core team members developing new things for the editor. The biggest gap in documentation I think has been with UI elements. Since the initial steps to deprecate space-pen, the official docs on atom.io/docs have not included anything about how to use UI elements.

I’ve been frustrated about this for a while and haven’t a chance or investment to bring this up but now I’m working on an atom package full time and feeling the pain even more.

I’d be happy to help start this if someone points me in the right direction.


#2

I agree that documentation about view elements is iffy. The best source is the etch documentation, but there are some gaps between where the Flight Manual leaves off and where the more technical docs expect you to be. I’m personally working on a project where I’ve had to cross that gap by myself, and it’s not inappropriate to describe it as a bit of a leap from one tree to another where there could easily be a walkable bridge. I haven’t had the time to distill my thoughts into new guidance for others, and I still don’t, but I’m completely down for working to lay some of the ropes for that bridge.

One important thing to keep in mind: any in-depth view tutorial should probably refer to etch, since it’s well-supported and lightweight, but it shouldn’t depend on a single library. Instead, it should focus on things like what the ViewRegistry is and how to think about serializing and deserializing when you have multiple views that get handled independently. Let’s start by making an outline. I’ll contribute those three points:

  • WTF is etch?
  • What’s the ViewRegistry?
  • Advanced serialization.

#3

Wow I even forgot about Etch. I didn’t realize it was still being used since they are using a lot of react for the GitHub package. You’re right though, etch should be referred for sure.

Those are great points you’ve mentioned to elaborate on. I’ve noticed some inconsistencies/gaps in the documentation of some elements. For instance, what prompted me to bring this up was that the <atom-text-editor> element property for placeholder used to be placeholderText but it wasn’t working and after digging through the source code, that property was renamed to placeholder-text and that information is not captured anywhere other than in the code.

So this documentation can be to describe how views work in atom (ViewRegistry, Etch, custom elements…) and then it can also have API documentation for using some the native atom elements like atom-tex-editor.

To me, ideally these things should be in the flight manual and the technical docs. I’d love input from @leedohm @nathansobo about whether we can contribute to that documentation.


#4

Interesting. I’ve been working with Etch and didn’t realize people were using React :). Anyway, the flight manual and docs are both github repos, I imagine you could just create a pull request.


#5

I had done a brief search for those repos but didn’t come up with anything. Do you know where they are?


#6

The Flight Manual is here. The API docs are generated from comments in Atom’s source code.


#8

He deleted it, but credit to @alflanagan for mentioning that you can get to the source code by pressing the <> button adjacent to an entry. That’s probably easy to overlook.


#9

Thanks. I figured you’d beat me to it.


#10

Thanks for the link to the flight manual repo. Yea I use the link to source code a lot so I definitely spaced in not remembering the docs are just the comments in code.


#11

Hello all.

What I am reading here is music to my ears…
I just wish I knew enough to contribute.

Would this platform be worth using for a small collaboration group?..
https://www.gitbook.com/

Cheers.