console.coffee documentation overview

[carocad]

Add an initial overview of how does the console works and which methods are expected to be used by the users

[MikeInnes]

Awesome, thanks a lot for these docs patches :+1:

This is a separate issue, but: Are all those steps really necessary to get a working console? If so, we should think about making the API simpler and stripping out anything that can have a sensible default (like console modes).

[carocad]

@MikeInnes you are welcome ;)

Regarding the steps, I guess that it depends on what you consider to be a 'working console'. If you consider it simply as a text pane where you can display things, then console.activate and console.setModes could be avoided. On the other hand, if you think of it as a language interface with history, commands, a grammar specification and so on, then all of those steps are required. At least that's the conclusion I came from after striping away most of the code from julia-plugin's to create a console from scratch. You can see a bare-bones console here: https://gist.github.com/carocad/6334a5d457b868e75da55f1b0233151c

I think that you could greatly simplify the API by simply providing a constructor method. You could pass the ID, URI and modes of the console. That would merge 3 of those steps. Furthermore you could put the atom.workspace.open call inside of activate (provided that the user got a console through the constructor, thus there is already a URI inside the console itself).

I think that would greatly simplify the process:

• construct a console with your language details
• activate the console

[MikeInnes]

Definitely agree that those sorts of things would be ideal. When I was initially implementing this stuff the issues I had were to do with pane opening and serialisation; Atom wasn't really designed to handle this kind of use case so it's a little weird. However, I think we can probably do things like having the Console class register an open that looks for atom://ink-console/[id] or something similar and responds appropriately – and then we can wrap that in a console.open() method which doesn't have to be reimplemented by the user every time.

[MikeInnes]

Ok, I had a go at reducing the opening steps at least; now it should just be a case of calling console.open() without all the mess of registering uri handlers or calling activate().

@carocad Please feel free to simplify things further, and let me know if you run into any further trouble. It may make sense to pass in a grammar name by default which avoids the first-time user having to think about console modes.

[carocad]

@MikeInnes that's great I'm happy to hear that

I have some notes on your code (I would like to understand it so I can put some notes ;) ), but I am really new to CoffeeScript so I am not sure if this comments are right or not, feel free to ignore them if so:

• aren't these lines conflicting? (see here and here). Also, when you call module.exports.deactivate, which subs is disposed, the one created on activate or the global one?
• I don't know where does Pane.name comes from since I couldn't find it neither in the Console class nor in the pane-mixin :(
• If I get the new code right, now the steps should be
  • get a console with ink.Console.fromId('id')
  • set console modes with console.setModes(modes)
  • open a console with console.open(options)

I think that the idea of putting a default mode for the console is great for beginners but I would put a console.warn('no console mode provided: using julia language') or something similar. That would probably help with some future headaches :)

[MikeInnes]

Hey @carocad, I think the code you linked it out of date (you can hit y when viewing a file to lock to the current commit) so I'm not sure if I've understood the first issue, but roughly the cycle goes as follows:

1. Package loads, create subs and register panes
2. Deactivate package, dispose subs
3. Activate package, recreate subs and re-register panes
4. goto 2

It's a little weird because of the need to register views as soon as the package loads so that panes can be correctly deserialised, but it should be correct.

Pane is a CoffeeScript Class, and classes have a name property for reflection. so Console.name == 'Console', Workspace.name == 'Workspace' etc.

I think you have the steps right.

I don't think I explained the "default mode" idea very clearly, but I didn't mean to make it implicit, just to make it simpler. So instead of doing

Console.setModes [{name: 'julia', grammar: 'source.julia'}]

you'd do something like

Console.fromId 'julia', grammar: 'source.julia'

Which is not as full-featured but makes things easier to understand for the beginner.