Uploaded image for project: 'Alloy'
  1. Alloy
  2. ALOY-1348

Provide better inline documentation/comments for generated files

    Details

    • Type: Story
    • Status: Open
    • Priority: None
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None

      Description

      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.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                fmiao Feon Sua Xin Miao
                Reporter:
                bgrantges@appcelerator.com Bert Grantges (Inactive)
              • Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Backbone Issue Sync

                  • Backbone Issue Sync is enabled for your project, but we do not have any synchronization info for this issue.

                    Git Integration