{
	"id": "154163",
	"key": "ALOY-1348",
	"fields": {
		"issuetype": {
			"id": "7",
			"description": "gh.issue.story.desc",
			"name": "Story",
			"subtask": false
		},
		"project": {
			"id": "11113",
			"key": "ALOY",
			"name": "Alloy",
			"projectCategory": {
				"id": "10400",
				"description": "Tools for developing applications",
				"name": "Tooling"
			}
		},
		"fixVersions": [],
		"resolution": null,
		"resolutiondate": null,
		"created": "2016-01-07T15:19:52.000+0000",
		"priority": {
			"name": "None",
			"id": "6"
		},
		"labels": [],
		"versions": [],
		"issuelinks": [
			{
				"id": "50239",
				"type": {
					"id": "10003",
					"name": "Relates",
					"inward": "relates to",
					"outward": "relates to"
				},
				"outwardIssue": {
					"id": "154144",
					"key": "ALOY-1346",
					"fields": {
						"summary": "Controller template should no longer declare args variable",
						"status": {
							"description": "The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.",
							"name": "Closed",
							"id": "6",
							"statusCategory": {
								"id": 3,
								"key": "done",
								"colorName": "green",
								"name": "Done"
							}
						},
						"priority": {
							"name": "Low",
							"id": "4"
						},
						"issuetype": {
							"id": "4",
							"description": "An improvement or enhancement to an existing feature or task.",
							"name": "Improvement",
							"subtask": false
						}
					}
				}
			}
		],
		"assignee": {
			"name": "fmiao",
			"key": "fmiao",
			"displayName": "Feon Sua Xin Miao",
			"active": true,
			"timeZone": "America/Vancouver"
		},
		"updated": "2016-01-07T15:24:25.000+0000",
		"status": {
			"description": "The issue is open and ready for the assignee to start work on it.",
			"name": "Open",
			"id": "1",
			"statusCategory": {
				"id": 2,
				"key": "new",
				"colorName": "blue-gray",
				"name": "To Do"
			}
		},
		"components": [],
		"description": "Alloy generates a number of different files for users, as well as file groups, for things like widgets. :\r\n\r\nExamples\r\n* Controllers\r\n* Views\r\n* TSS\r\n* Models\r\n\r\nWhile 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.\r\n\r\nFor example today when a user creates a new controller (using `alloy generate` or Studio) the following code is generated:\r\n\r\n~~~\r\nvar args = arguments[0] || {};\r\n~~~\r\n\r\nThere 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).\r\n\r\n> 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.\r\n\r\nAn example of a new controller file might look like this:\r\n\r\n~~~\r\n/* myfilename.js\r\n * This is the alloy controller file for the myfilenameview. All business logic related to this view\r\n * should be placed within this file.\r\n *\r\n * To access arguments passed into this view using Alloy.createController() can be referenced\r\n * on the controller controller accessible object like this -> $.args.myArgument\r\n * \r\n * Functions and properties you wish to make public, or accessible outside of this controller\r\n * should be exported or attached to the controller object ($).\r\n *\r\n * Example:\r\n *      exports.myFunc = function(val) { alert(val) };    OR     $.myFunc = function(val) { alert(val) }; \r\n *\r\n * Functions and properties that are not made public, are considered private an only\r\n * accessible to this controller.\r\n *\r\n * More on Alloy controllers can be found in our documentation here:\r\n * http://docs.appcelerator.com/platform/latest/#!/guide/Alloy_Controllers\r\n *\r\n * To turn off generated comments, you can do so using the following command from your\r\n * terminal \r\n * \r\n *     alloy set config inlineComments false\r\n * \r\n * Or from your studio preferences\r\n */\r\n\r\nWhile 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.\r\n\r\nAs 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.\r\n\r\nA good example of this helpful commenting is already available in the new \"wizard\" flow for Arrow connectors.",
		"attachment": [],
		"flagged": false,
		"summary": "Provide better inline documentation/comments for generated files",
		"creator": {
			"name": "bgrantges@appcelerator.com",
			"key": "bgrantges",
			"displayName": "Bert Grantges",
			"active": false,
			"timeZone": "America/Chicago"
		},
		"subtasks": [],
		"reporter": {
			"name": "bgrantges@appcelerator.com",
			"key": "bgrantges",
			"displayName": "Bert Grantges",
			"active": false,
			"timeZone": "America/Chicago"
		},
		"environment": null,
		"comment": {
			"comments": [
				{
					"id": "374017",
					"author": {
						"name": "bgrantges@appcelerator.com",
						"key": "bgrantges",
						"displayName": "Bert Grantges",
						"active": false,
						"timeZone": "America/Chicago"
					},
					"body": "Initial reference for this feature can be found in the linked ticket.",
					"updateAuthor": {
						"name": "bgrantges@appcelerator.com",
						"key": "bgrantges",
						"displayName": "Bert Grantges",
						"active": false,
						"timeZone": "America/Chicago"
					},
					"created": "2016-01-07T15:20:35.000+0000",
					"updated": "2016-01-07T15:20:35.000+0000"
				},
				{
					"id": "374018",
					"author": {
						"name": "fokkezb",
						"key": "fokke",
						"displayName": "Fokke Zandbergen",
						"active": true,
						"timeZone": "Europe/Amsterdam"
					},
					"body": "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).",
					"updateAuthor": {
						"name": "fokkezb",
						"key": "fokke",
						"displayName": "Fokke Zandbergen",
						"active": true,
						"timeZone": "Europe/Amsterdam"
					},
					"created": "2016-01-07T15:24:25.000+0000",
					"updated": "2016-01-07T15:24:25.000+0000"
				}
			],
			"maxResults": 2,
			"total": 2,
			"startAt": 0
		}
	}
}