ScriptDoc Forums

Spec Discussion :: RE: @singleton

Author: klindsey
Posted: Fri Nov 21, 2008 5:55 pm (GMT 0)
Topic Replies: 1

Hi David,

This too being actively discussed with the OpenAjax Alliance. This will be included in sdoc once it shows up in the OAA spec.

Thanks,
Kevin Lindsey
Aptana, Inc. - http://www.aptana.com

Spec Discussion :: RE: @licence and @copyright @event

Author: klindsey
Posted: Fri Nov 21, 2008 5:05 pm (GMT 0)
Topic Replies: 1

Hi David,

We are working as members of the OpenAjax Alliance in the creation of an API metadata format. As the API specification evolves and as Aptana adopts those changes, we will necessarily have to make sure that scriptdoc also has syntax to capture the semantics as described in the API spec. It looks like we have license and event covered as seen in the following URLs.

http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification_Descriptive#License_elements
http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification_API_Metadata#Event_elements

I wasn't able to locate anything with regards to copyright info, so we'll bring that up with OAA and see if that can be included and even if that doesn't get in, scriptdoc and OAA both allow for extensibility. "copyright" could be an extension, if necessary.

Thanks,
Kevin Lindsey
Aptana, Inc. - http://www.aptana.com

Spec Discussion :: Building documentation from command line

Author: facconi
Subject: Building documentation from command line
Posted: Tue Nov 18, 2008 12:04 pm (GMT 0)
Topic Replies: 0

Hi everybody. I am using ScriptDoc for my projects and I build the documentation using Aptana Studio Professional.

I would like to build documentation using the command line (Linux or Mac Os X), is it possible to do so? Is there any tool to do so?

Thank you,
Francesco

Spec Discussion :: RE: Scriptdoc Status

Author: klindsey
Posted: Mon Nov 17, 2008 11:41 pm (GMT 0)
Topic Replies: 1

Hi CriticalMass,

Yes, most of the new ScriptDoc work has been implemented in Jaxer, but honestly, we introduced some workarounds to create a better XML file used in Studio for code assist (and for doc gen). We will be rectifying this in the future.

We've been very active with the Open AJAX Alliance and the work they are doing for the API metadata format. There are still a few items that need to be resolved and once those are complete, then we can address how missing concepts are going to be expressed in ScriptDoc comments. For example, there has been lively discussion regarding how to capture functions and options objects that are arguments to a function.

Regarding a roadmap, I can't give you anything specific at this point in time. I can say that code assist (which includes ScriptDoc) is on the agenda for Aptana Studio 1.3, so we will be discussing and prioritizing this work soon.

Thanks,
Kevin Lindsey

Spec Discussion :: @licence and @copyright @event

Author: ramaboo
Subject: @licence and @copyright @event
Posted: Sun Nov 16, 2008 7:34 am (GMT 0)
Topic Replies: 1

@licence might be useful as well.
@copyright seems to be in most of the other documentation standards as well.

I love the idea of a documentation standard. I hope this one gets updated soon since it seems like it does not support a lot of the obvious tags at the moment.

@event would also be a good candidate for inclusion.

David

Spec Discussion :: @singleton

Author: ramaboo
Subject: @singleton
Posted: Sun Nov 16, 2008 7:28 am (GMT 0)
Topic Replies: 1

@singleton should be included in the spec.

Spec Discussion :: Scriptdoc Status

Author: CriticalMass
Subject: Scriptdoc Status
Posted: Wed Nov 05, 2008 12:31 am (GMT 0)
Topic Replies: 1

Just wanted to inquire if there is still continuing development for this project. From reading through the posts here, there seems to be a more advanced version used internally on Jaxer. Is there any intention to release the great un-washed?

I'm currently looking to document a quite large JS project and as I use Aptana I've been looking at scriptdoc. I get the feeling this is an unfinished app. The documentation and intro screencast both seem to be at odds with the actual implementation. The most disappointing aspect for me is rendering/export of the docs as HTML: it's just plain broke/unusable.

I would like to know the roadmap; if there is to be no further (in the near future) improvements I will need to take an alternative route (perhaps JSDoc). One which uses a proper hyper-text paradigm (like JavaDoc/JSDoc): I would just love the Aptana integration.

Spec Discussion :: RE: TOC

Author: hudlin
Posted: Tue Sep 23, 2008 11:52 am (GMT 0)
Topic Replies: 2

thanks klindsey
_________________
"... for freedom I give you security, ..."

Spec Discussion :: RE: TOC

Author: klindsey
Posted: Tue Sep 16, 2008 8:50 pm (GMT 0)
Topic Replies: 2

Hi Hudlin,

I've added a short list of links to the top of that page.

HTH,
Kevin

Spec Discussion :: TOC

Author: hudlin
Subject: TOC
Posted: Tue Sep 16, 2008 10:25 am (GMT 0)
Topic Replies: 2

How about a table of contents at the top of the specification so readers can quickly jump to the bit they care about? Might be useful when using the specification as a reference
_________________
"... for freedom I give you security, ..."

Spec Discussion :: Documenting 'classes'

Author: DavidFoley
Subject: Documenting 'classes'
Posted: Sat Jul 19, 2008 3:19 pm (GMT 0)
Topic Replies: 0

I hope this is relevant to the forum, if not, my apologies - the issue sits ambiguously been implementation and specification (to my eyes, anyway)

Basically, I'm developing a framework/library (http://ecmajex.wiki.sourceforge.net/) that implements a number of extensions to Function to make some OOP techniques more intuitive. These extended methods are therefore available on all constructors (and functions as it happens). I'm interested in using ScriptDoc to document the code base, but I've found that it doesn't appear to recognize members of classes because of the way classes are defined in this library.

The point is that it appears that it is not possible to document function parameters, on a per parameter basis, within a method call. However, this is precisely how classes are defined in jex.

To put it in perspective, this is an example of how you would define a class and then a subclass in the jex framework. I have added ScriptDoc comments as I understand how they should be used, and inline comments to provide some context (which of course have no bearing on ScriptDoc)

Code:

      // the Function#define method extension takes any
// number of properties and named functions (as
      // opposed to anonymous functions) and appends them
// to the prototype of the Function upon which the define
// method has been called.

      // Objects are iterated, and their properties are
      // then appended to the calling functions prototype.

      // note that Function.prototype.define takes members
// as parameters, i.e.members are are defined
      // within the call operator ( ).

      Superclass.define
      (
         {
            /**
            * @type {String}
            *    An example property defined
            *    on the Superclass.prototype
            * @memberOf Superclass
            */
            property : null
         },

         /**
         * A method of Superclass
         * @method
         * @memberOf Superclass
         * @return {String}
         *    the value of property, or a default value
         */
         function method ()
         {
            return isSetOr(this.property, "defaultValue");
         }
      )

      /**
      * A class definition for the class Superclass
      * @classDescription
      *    create a new instance of Superclass
      * @param {String} value
      * a string value to paramaterise the instance
      * @return {Superclass}
      * @exception {TypeError}
      * thrown if any non-string value is passed
* @constructor
      */
      function Superclass (value)
      {
         if(String.type(value))
         {
            this.property = value;
         }
         else
         {
            throw new TypeError("String expected");
         }
      }

      // .. and this is how you subclass

      /**
      *@inherits {Superclass}
      */
      Subclass.inherits(Superclass);
      Subclass.define
      {
         /**
         * A method of subclass. It
         * calls the inherited 'method'
         * method
         * @method
         * @memberOf Subclass
         * @return {String}
         *
         */
         function getProperty ()
         {
            return this.method();
         }
      }

      /**
      * A subclass of superclass
      * @classDescription blah
      * @return {Subclass}
* @constructor
      */
      function Subclass ()
      {
         Superclass.call(this, "propertyValue");
      }

      // end of javascript

I've tried linking .sdocs, as well as defining comments in class files in and around properties and methods I want to document (as in the example above), but I don't get what I expect.

To qualify, when I publish html docs, the only details I see concern constructors - property, method and getMethod, for example, do not appear in the documentation.

Is this because I'm using named functions within the call operator of Function#define? ScriptDoc doesn't appear to be able to read them.

If this is the case, I would recommend making this possible, after all, ScriptDoc should not make assumptions about how classes are defined in order to document them (if that is the case).

Then again, I may be missing something, in which case, I would appreciate advice.

ScriptDoc is a great utility, and it works fine for more conventional ways of defining objects. If this is an implementation issue, and not a specification issue, please point me in the right direction. Thanks!

Best,

David.

Spec Discussion :: Generating the docs

Author: nanich
Subject: Generating the docs
Posted: Wed Jul 09, 2008 6:33 pm (GMT 0)
Topic Replies: 0

Can anybody please help me in generating the javascript docs. I couldn't find this information at any part of the site. Kindly help me

Spec Discussion :: A few suggestions

Author: Cidolfas
Subject: A few suggestions
Posted: Thu Apr 10, 2008 10:13 pm (GMT 0)
Topic Replies: 0

I've been using JSDoc for a while, and I have a few things that I'd like to see either from it or added to it.

-The ScriptDoc spec doesn't seem to have the capability of describing a parameter of being one of several types using the | separator. This would be very useful.

-JSDoc has an @link tag which can be used anywhere in any description and acts similar to @see. I'd very much like to see that as well.

-What about @private and @protected? This would be useful as well; @protected could be used for folks who want to extend the framework, and @private for truly private variables which shouldn't be touched.

-I'd like to see an @package or @module to group arbitrary classes together.

Looks like a cool initiative! For the Aptana folks, are there any plans to release your ScriptDoc parser as a standalone program, i.e. outside the Aptana Studio? Even as a command-line executable, perhaps?

Spec Discussion :: RE: Value Constraints ?

Author: Cidolfas
Posted: Thu Apr 10, 2008 10:02 pm (GMT 0)
Topic Replies: 1

Could you not just include that in the description of the item you're documenting?

Spec Discussion :: RE: Proposal for declaring Function parameters and return types

Author: Cidolfas
Posted: Thu Apr 10, 2008 10:02 pm (GMT 0)
Topic Replies: 2

Looks good to me.