Uploaded image for project: 'Aptana Studio'
  1. Aptana Studio
  2. APSTUD-4454

SDOC specification in documentation does not describe current implementation / current SDOC implementation is undocumented

    Details

    • Type: Improvement
    • Status: Open
    • Priority: Low
    • Resolution: Unresolved
    • Affects Version/s: Aptana Studio 3.1.0
    • Fix Version/s: None
    • Component/s: Documentation
    • Labels:
    • Story Points:
      0

      Description

      The "ScriptDoc (SDOC) 2.0 Specification" described by https://wiki.appcelerator.org/display/tis/ScriptDoc+%28SDOC%29+2.0+Specification is not implemented by Aptana Studio, and the implementation of ScriptDoc that is supported is not documented. Comparing the implementation found in https://github.com/aptana/studio3/tree/development/plugins/com.aptana.editor.js/src/com/aptana/editor/js/sdoc, the following differences can be noted:

      • @advanced: Implemented, but not documented.
      • @alias: No real discrepancies, but the documentation looks like a function call followed by an object literal, where the intent is obviously either a function declaration or object literal and not both.
      • @classDescription: The parser's implementation (/parsing/SDocParser.java) appears to require braces around a namespace parameter, which is not documented.
      • @id: Listed in the specification, but has no corresponding representation in the source's model folder, nor a corresponding terminal in parsing/Terminals.java.
      • @inherits: Not implemented, but present in specification.
      • @extends: Implemented, but not present in specification. It appears to use a different syntax than that documented for @inherits in that @extends requires braces around its type expression.
      • @memberOf: Documented, but not implemented. This is really important to library writers and users.
      • @namespace: Implementation uses braces around the namespace name as if it is a type expression. Documentation lists the parameter without braces.
      • @overview: Implemented, but not documented.
      • @projectDescription: Documented, but not implemented.
      • @see: Implementation requires braces around the parameter in /parsing/SDocParser.java.
      • @userAgent: Implemented, but not documented.

      In addition, the "ScriptDoc tag quick reference" on the Appcelerator wiki https://wiki.appcelerator.org/display/tis/ScriptDoc+tag+quick+reference lists two tags (@native and @sdoc) that are neither listed in the specification nor implemented in the source (as far as I can tell).

      Finally, the implementation includes a "Class<...>" wrapper for type expressions, which is not documented.

      Please fix either the documentation or the implementation so that they match.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                pinnamuri Praveen Innamuri (Inactive)
                Reporter:
                sqykly David Hand
              • Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Git Source Code