Documentation: Each Atom Editor Feature Needs Documentation


#1

At the very minimum, each editor menu feature should be well documented.

This could be a “Help” item. The current Help > Documentation is not oriented towards use of the editor, but rather configuration, programming, what bundles are etc. This is good, but is not editor documentation.

– Owen


#2

I think as Atom passes the v1.0 barrier that things will naturally shift towards more documentation. Right now, though, Atom is a bit too much of a moving target to keep loads of documentation up-to-date with it.


#3

Maybe open up the GitHub WiKi to act like a temporary hub for notes?


#4

There is still an alarming number of functions not documented. I seem to stumble upon more everyday when fixing a bug in another package.

Some that come to mind are:
TextEditor.tokenForBufferPosition
TextEditor.displayBuffer.bufferRangeForScopeAtPosition

I understand what these functions are for now but there is no documentation for these functions anywhere.

They should at least be mentioned on https://atom.io/docs/api/v1.7.3/TextEditor


#5

Do you care to start a list of the ones you’ve encountered and start an issue or Discuss thread about it? Since the documentation wasn’t finished when those functions were written, it would be most expedient to put the information in a centralized list so that it’s easy to reference. That would also allow interested users to pick a function and explore it.


#6

I don’t know that I would be the best one to pick out functions that need documentation. I am relatively new to Atom and if I were to list every function that needs documentation it would be every public function in the atom/src directory.


#7

It’s not something that just one person should be expected to manage (unless they’re getting paid). I’m brand new to Atom and have no idea what functions need documentation, but a list of ones where information is lacking or absent would save me a lot of headaches in trying sift through what’s there. It just needs someone to start it, and you have recent experience with a few of them.


#8

Some functions are intentionally not documented. These are called “undocumented features” and should not be relied upon because they can change at any time. Having a 100% public documented API would make it so that we couldn’t change anything to say … increase performance.

If you have a question about particular functions, please post here, do not post an Issue about it.* There are occasions that we make a mistake and do not document functions that should be documented. Most of the time people who are writing packages will let us know that there is a function they use fairly often and have come to rely on and we’ll correct the mistake, if there was one.

The two functions that you mention at this point are intentionally undocumented.


* We’re trying to control the amount of Issues that we have to triage and track. For general questions, the Atom message board is where you’ll probably be able to find answers faster.


#9

I understand the need for undocumented functions. However public functions in the TextEditor class should never change (at least not within major versions). You can still optimize the function without changing what is input or output.

I believe the rule of thumb should be that all public functions that are used by the packages created by the Atom team should be well documented because they know best what is needed for creating packages. After all the API documentation is really only used for creating packages and if there is no easier way to do something then that function will probably be useful to someone else creating a package.

Both of the two functions I listed I found by looking at source code of packages created by the Atom team.


#10

I understand that documentation is not something every developer enjoys writing, however documenting how to create robust packages and having a good API should be one of the highest priorities for an editor known to be easily hackable.


#11

How we indicate what is “public” is if it is documented.

Yes, it is a very high priority for us, that is why we have all of the documentation we do have and strive to maintain it.

I feel the implication here is unfair and the phrasing is condescending. It’s fine if we disagree on how things should be documented.


#12

Sorry, I didn’t mean for that to sound condescending. I said that because I hate writing documentation.

I don’t understand how a function that is used by many packages (at least three that I know of), including a package that is written by the Atom team, and any package has the ability to call without any dependencies can be called private.

As far as I know there is no way other than using TextEditor.tokenForBufferPosition to get the token for a given buffer position other than manually traversing the DOM and pulling out the relevant information. This seems like something that would be useful for many packages.


#13

There are many things that would be useful for packages in the Atom codebase. The Atom team doesn’t have the resources to support all of them at the level that we expect of ourselves for our documented interface.

You seem to agree that it is valid to have undocumented or unsupported features in an application. So what is your proposal for features that we aren’t ready to document, publish and support as part of the “public” API?


#14

As an open source project, Atom encourages random people to mess around with it and use its functions. Obviously, anybody can sift through the source code and pull out every callable function, some of which might be legacy code, but then there are some packages that actively use these undocumented functions. Packages, even core ones, are separate from the base program. When people like us try to figure out how to write new things for this editor we like, we’re going to look first at packages that do roughly similar things.

I believe that I’m on the same page as @UziTech in believing that, when a function is used in a package but doesn’t have any information available on it outside of the source code, that’s an issue. If it’s on a list of methods that are works in progress, deprecated, or otherwise prone to change in the foreseeable future, then that’s useful information for us randos. Instead of talking about mysterious undocumented functions, we can talk about whether or not we believe a particular function merits inclusion in the public API. If a member of the community stumbles upon a function that they love, but the devs believe that it’s not ready for whatever reason, the community member could work to make it ready. That’s something that can’t happen if this information isn’t readily available and we have to have this discussion about documentation every time.


#15

I understand that there can be undocumented features. I do not believe that it is valid to have undocumented features on a public API.

As I said above:

I agree with @DamnedScholar, at the very least all functions should be listed with a short description of what they do and whether they are solid functions.


#16

Actually, as the OP, I’ve found that the existing docs, the help menu, the package search and settings, the forums, and just plain googling solves most problems for me, so this is no longer an issue.


#17

So we all seem to be agreeing that it is valid to have undocumented features. We’re disagreeing on how to implement or communicate that. I appreciate the feedback and your opinions. We’re not going to be changing our system of documentation at this time. If you need more clarification on how the documentation system works, I’m happy to supply that.


#18

I disagree. I don’t see any benefit to having undocumented features in a public API. If a feature exists in a stable branch of the API any package can use that feature which means changing that feature will most likely break something. And since the public API is there to help develop packages what is the point of having a feature that developers can’t easily find?


#19

essentially an unstable feature should not be in the stable branch. And all stable features should be well documented.


Documentation Driven Development
How can we help you write packages?