[ALOY-1348] Provide better inline documentation/comments for generated files

GitHub Issuen/a
Affected Version/sn/a
Fix Version/sn/a
ReporterBert Grantges
AssigneeFeon Sua Xin Miao


Alloy generates a number of different files for users, as well as file groups, for things like widgets. : Examples * Controllers * Views * TSS * Models While this is helpful, we do not really clarify what these files are used for. While experienced developers, probably don't need them, adding inline documentation/comments for these files would be very useful to help people just getting started understand how all the files relate together. For example today when a user creates a new controller (using alloy generate or Studio) the following code is generated: ~~~ var args = arguments[0] || {}; ~~~ There is no explanation for what that is or how or why to use that code. I propose that we provide better inline commenting to help new developers on Appcelerator better understand what is going on in each of the 3 files (along with links to docs). > NOTE: I would also propose that there would be a alloy config and/or flag to turn this off globally and/or at command time. An example of a new controller file might look like this: ~~~ /* myfilename.js * This is the alloy controller file for the myfilenameview. All business logic related to this view * should be placed within this file. * * To access arguments passed into this view using Alloy.createController() can be referenced * on the controller controller accessible object like this -> $.args.myArgument * * Functions and properties you wish to make public, or accessible outside of this controller * should be exported or attached to the controller object ($). * * Example: * exports.myFunc = function(val) { alert(val) }; OR $.myFunc = function(val) { alert(val) }; * * Functions and properties that are not made public, are considered private an only * accessible to this controller. * * More on Alloy controllers can be found in our documentation here: * http://docs.appcelerator.com/platform/latest/#!/guide/Alloy_Controllers * * To turn off generated comments, you can do so using the following command from your * terminal * * alloy set config inlineComments false * * Or from your studio preferences */ While this may seem a bit verbose, adding comments like this to all generated files can be a really helpful way to ensure developers are doing things correctly and better understand how to get started. As noted in the comment above, there should be a config entry to bypass these generated comments that can be set either through the command line OR from Studio. Setting the flag in studio would set the command for the alloy CLI as well. A good example of this helpful commenting is already available in the new "wizard" flow for Arrow connectors.


  1. Bert Grantges 2016-01-07 Initial reference for this feature can be found in the linked ticket.
  2. Fokke Zandbergen 2016-01-07 I'd suggest we first resolve ALOY-1346 by updating var args = arguments\[0\] || {} to the more appropriate var args = $.args, then discuss this ticket but at the same time also look at allow users to point to a specific template to use when generating (appc alloy generate controller -t path (which is basically the same as appc alloy copy path target btw).

JSON Source