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 Improvement
    • Status: Open
    • Priority: Medium Medium
    • Resolution: Unresolved
    • Affects Version/s: Aptana Studio 3.1.0
    • Fix Version/s: Backlog
    • 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.

        Issue Links

          Activity

          Hide
          Ingo Muschenetz added a comment -

          Thank you very much for your exhaustive investigation! Studio 3 re-implemented ScriptDoc functionality, and as you point out, there are discrepancies. We'll investigate what the proper fix is in each case and update the ticket.

          Show
          Ingo Muschenetz added a comment - Thank you very much for your exhaustive investigation! Studio 3 re-implemented ScriptDoc functionality, and as you point out, there are discrepancies. We'll investigate what the proper fix is in each case and update the ticket.
          Hide
          David Hand added a comment -

          No problem! I would really like to make strong Aptana content assist a feature of a JS library I'm developing, so going through all this was helpful to me, too.

          I wanted to take this a step further and find out which tags now affect content assist and how, but I couldn't find enough of the code that's actually gathering SDOC for content assist. I see getDocumentation/setDocumentation in the JS AST, but it's unclear where the data goes and when it's happening. It looks like it's integrated differently than the other sources of documentation, which have index writers and such.

          In particular, the use and namespace of parameters for the tags @namespace and @alias is not straightforward, if indeed these tags are being used by content assist. For other tags, a type name is the only logical parameter, but the names of these two tags sound like they might want something else, and it could conceivably be an identifier from the source or a type name or something different entirely.

          Show
          David Hand added a comment - No problem! I would really like to make strong Aptana content assist a feature of a JS library I'm developing, so going through all this was helpful to me, too. I wanted to take this a step further and find out which tags now affect content assist and how, but I couldn't find enough of the code that's actually gathering SDOC for content assist. I see getDocumentation/setDocumentation in the JS AST, but it's unclear where the data goes and when it's happening. It looks like it's integrated differently than the other sources of documentation, which have index writers and such. In particular, the use and namespace of parameters for the tags @namespace and @alias is not straightforward, if indeed these tags are being used by content assist. For other tags, a type name is the only logical parameter, but the names of these two tags sound like they might want something else, and it could conceivably be an identifier from the source or a type name or something different entirely.

            People

            • Assignee:
              Praveen Innamuri
              Reporter:
              David Hand
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:

                Development