☔️ Turn on the lights

[andymatuschak]

@jbrennan, @may-li, and I all independently came to the same conclusion while trying to actually use Prototope-JS to make prototypes: the biggest issue isn't any particular missing feature, it's that we feel like we're fumbling around the in the dark. Poor (JS) documentation, unhelpful failure modes, and indifferent editor tooling are the worst offenders.

I have some pragmatic ideas, though:

• Documentation
  • [x] JS Documentation. We need a switch or something that can flip the current docs into "JavaScript mode." This will require writing JS signatures for the docs.
  • [ ] Finished API documentation. We're missing docs for a ton of the APIs.
  • [ ] High-level documentation. Giving a method listing is useful, but many of the types are missing good high-level documentation: what is this thing for, how does it relate to other things, what's an example?
• Failure Modes
  • [x] Enable "use strict"; on all prototypes. (#36) This will make protonopes for certain common errors (e.g. using a variable that hasn't yet been declared).
  • [ ] Add argument checking on all APIs. I think this'll be big. We should write a macro we can use to assert the types of all the JS arguments at runtime. So if you pass a double to something expecting a Point, you'll get a protonope. Similarly, for APIs which take a hash, we should protonope if you pass an unexpected key or if you're missing a required key.
  • [ ] Convert crashes to protonopes. Before the JS bridge, I was pretty aggressive about letting the prototype crash if something went wrong. That doesn't make sense in this context. Key examples are e.g. missing images or missing named layers. We should audit the project for fatalError and !, and we should convert them all to protonopes (i.e. via Environment.exceptionHandler). Partially addressed in #45.
• Editor Tooling
  • [ ] Autocomplete. We need some kind of basic autocomplete environment for Sublime or TextMate or something. Unfortunately, from what I've seen so far, their autocomplete functions don't permit showing documentation (as Xcode and other IDEs do). (update: using Tern helps somewhat!)
  • [ ] Realtime linting. Can we do a realtime pass on syntax in the editor before going all the way to the device?
  • Any other low-hanging, pragmatic things we can do from Learnable Programming?

Any other ideas @saniul, @nsfmc?

[jbrennan]

The editor I use (Chocolat) will show documentation in its autocomplete but I’m not sure if that can be third-party docs.

Good list though!

[andymatuschak]

Yo, @jbrennan, Chocolat's autocomplete is sweet!

Asked on their IRC chan how to make docs show up in autocomplete. I see how to make a new completions list but not how to hook docs up to it. No answer yet.

[jbrennan]

Chocolat is a p nice editor, although unfortunately I find it's sometimes kinda buggy. But I like it so much more than Sublime or Textmate. Works well for prototoping.

[kevinbarabash]

When using JavaScript it would be nice to have a way to way to break on the first instruction so that a person can open up the Safari web inspector or at somehow keep the web inspector open between compile cycles. If I knew how to use protocaster to do live coding this may be less of an issue.

[andymatuschak]

@jbrennan Happy to suggest Chocolat as official editor if we can get docs+completion working. Still no answer in IRC.

@kevinb7 That would be sweet. react-native manages this, but through greater control over execution paths than we may have. Not immediately sure how to make that happen. In the meantime, a quick Protocaster guide (docs will happen! I promise!):

1. A prototype is a folder with a single .js file and images (.png), sounds (.wav, .aif) or movies (not yet supported via broadcast).
2. Launch Protocaster on your Mac and Protoscope on an iOS device or the iOS simulator.
3. Choose your prototype and target device in the Protocaster UI. The device will have to be on the same network.

Ta-da!

[kevinbarabash]

@andymatuschak Thanks. I'll give that a try.

[jbrennan]

Some progress on Chocolat docs

[saniul]

:+1: to everything in the list. JS autocomplete would be so, so helpful.

I haven’t looked at Chocolat yet, but I imagined Atom could end up being a platform for a future prototope editor, since it’s open and extendable (RE: incorporating Learnable Programming ideas).

[jbrennan]

Yeah I kind of forgot about Atom. It might be a better option because it's more hackable.

I kind of don't want to spend too much time trying to apply LP ideas to the JS bridge because I feel like there would be better ways to approach the problem (not via a bridge). So often I just want to draw the prototype layers! Don't get me wrong, I love love love the principles of LP, but I don't want to march too far down the wrong branch.

[andymatuschak]

I looked into Atom, but it doesn’t seem to have any way to present docs in autocomplete.

Agree with you about LP + JS, Jason: this is a pragmatic, hacky solution until someone (else) solves it for real. Let’s not go way out of our way.

On Mar 2, 2015, at 2:39 PM, Jason Brennan notifications@github.com wrote:

Yeah I kind of forgot about Atom. It might be a better option because it's more hackable.

I kind of don't want to spend too much time trying to apply LP ideas to the JS bridge because I feel like there would be better ways to approach the problem (not via a bridge). So often I just want to draw the prototype layers! Don't get me wrong, I love love love the principles of LP, but I don't want to march too far down the wrong branch.

— Reply to this email directly or view it on GitHub https://github.com/Khan/Prototope/issues/33#issuecomment-76842672.

[saniul]

RE:

Convert crashes to protonopes

I took care of some low-hanging fruit in https://github.com/Khan/Prototope/pull/45

[andymatuschak]

💯

[nsfmc]

all future enhancements should probably target javascript, right? so docs, syntax definitions/ snippets and linting and so forth should all be focused on js rather than swift. any more recent word on chocolat? i was looking at sublimelinter the other night which seems modular enough that we might be able to use it for realtime checking (at least its perf with eslint is pretty good)

[andymatuschak]

Yeah, focus on JS, I think.

Tern (the static analysis + autocompletion tech Chocolat uses, which also has Sublime, vim, etc plugins) is promising, and I’ve structured the changes to the docs for JS s.t. we should be able to write a transformer for tern definition files.

On Mar 14, 2015, at 4:20 PM, Marcos Ojeda notifications@github.com wrote:

all future enhancements should probably target javascript, right? so docs, syntax definitions/ snippets and linting and so forth should all be focused on js rather than swift. any more recent word on chocolat? i was looking at sublimelinter the other night which seems modular enough that we might be able to use it for realtime checking (at least its perf with eslint is pretty good)

— Reply to this email directly or view it on GitHub https://github.com/Khan/Prototope/issues/33#issuecomment-80758963.

[andymatuschak]

Visual Studio Code does realtime linting. Looks like we could get autocomplete by providing TypeScript specs…