PDA

View Full Version : [DUP] SA2 should provide a way to add doc comments to classes, methods, properties...



apsq
29 Aug 2012, 4:44 AM
Compared to ExtDesigner, SA2 is actually pretty good when it comes to using it to generate ExtJS code. However there is one big thing missing from SA2 that would be expected from any human "generating" the code: doc comments.

Since we're using JSDuck to generate documentation for our ExtJS projects from the source code, this shortcoming is rather annoying. It's technically possible to add comments inside function bodies, but this violates the code conventions used outside SA2. Currently the only way to add proper documentation for classes, methods, properties, configuration and so on is to add them to a plain text file not managed by SA2. This creates a greater risk of the documentation falling out of date and is all around a bad solution.

It would be nice if SA2 had additional fields (like the displayName etc) to hold this kind of information that would be emitted as doc comments in the appropriate places. A simple field that appears on classes and functions (read: functions, event bindings, etc) would be sufficient, although more contrived solutions would be imaginable.

Note that SA2 does not need to be at all intelligent about the comments' semantics (in fact, this would aid interoperability with other code documentation generation tools that are incompatible with JSDuck). It only needs to provide a simple unformatted text field.

aconran
29 Aug 2012, 7:26 AM
We're aware of this and looking to address it.

apsq
29 Aug 2012, 9:46 AM
Awesome, thanks.