Visual Studio - JavaScript自定义对象的智能感知功能

Question

我创建了以下JavaScript对象：

var Content = Content || {};

// Constructor defines properties and inits object
Content.ProductManager = function () {
    // ...
};


Content.ProductManager.prototype = function () {

    // 
    // private members
    // 


    var setProductAsPreviewed = function (args) {
        // code omitted for brevity
        // ....
    };


    //
    // public members
    // 

    return {
        setProductAsPreviewed: setProductAsPreviewed
    };

} (); 

传递给 setProductAsPreviewed 的对象具有以下属性：

args = {
    productId: int,
    productName: string,
    updateDate: date,
    saveItems: bool
};

我想加入XML注释，以便在函数setProductAsPreviewed中传递的参数上获得智能感知：

var productManager = new window.Content.ProductManager();
// show intellisense when typing the following:
productManager.setProductAsPreviewed( 

这个帖子展示了如何为简单参数（string，int等）注释JavaScript方法，但是如何针对一个复杂对象注释呢？我正在使用Visual Studio 2010。

- Rui Jarimba

---

你的 args 对象是即时生成的，还是有自定义函数定义类型？ - Sean Airey

它们是在调用函数productManager.setProductAsPreviewed时动态生成的。是否定义一个具有所需属性的对象以便拥有智能感知是个好主意？我一直试图避免这样做，因为这是我唯一使用此对象的地方。 - Rui Jarimba

我把我的评论改成了答案。不过我可能是错的，因为我对JS智能感知的大部分了解都来自于VS2012，所以我会等一段时间让其他人考虑一下 =] - Sean Airey

刚刚快速查看了一下并做了一些谷歌搜索，但无法找到任何与此有关的有用信息，即使是 MSDN 文档在这方面也非常糟糕，尽管它似乎只支持函数的内联文档，因为它们只提到了 <param>、<field> 和 <returns>：http://msdn.microsoft.com/en-us/library/bb514138(v=vs.100).aspx - Sean Airey

Answer 1

据我所知，如果一个泛型变量被用作参数，你不能告诉IntelliSense该变量有哪些字段和方法。

如果这个变量是一个数组，你可以像这样定义它：

function funcWithArrayArg(arrayArg) {
    /// <param name="arrayArg" type="Array" elementType="Number">An array of numbers</param>
}

在VS2012中，您也可以对对象进行注释，就像这样（您可以注释用作对象构造函数的函数上的字段，就像我下面演示的一样，但文档没有关于这样的匿名对象的说明）：

var args = {
    /// <field type="Number">Product ID</field>
    productID: int
};

这两种方法都不能满足您的需求，因为第二种方法无法在函数参数上提供智能感知功能，而且您正在使用VS2010。

我认为最好的办法是定义一个自定义对象作为参数对象，只用于该函数。毕竟，如果想要创建一个带有智能感知的自定义对象作为参数，在其他语言中也是这样做的。它可能看起来像这样：

function ProductPreviewArgs(productId, productName, updateDate, saveItems) {
    /// <summary>Creates an object for use as the sole argument to the setProductAsPreviewed function</summary>
    /// <param name="productId" type="Number" optional="false">The Product ID</param>
    /// <param name="productName" type="String" optional="false">The Product Name</param>
    /// <param name="updateDate" type="Date" optional="false">The date the product was last updated</param>
    /// <param name="saveItems" type="Boolean" optional="false">Specifies whether or not to save the items</param>
    /// <returns type="ProductPreviewArgs">An object intended for use as the sole argument to the setProductAsPreviewed function</returns>
    /// <field name="productId" type="Number">The Product ID</field>
    /// <field name="productName" type="String">The Product Name</field>
    /// <field name="updateDate" type="Date">The date the product was last updated</field>
    /// <field name="saveItems" type="Boolean">Specifies whether or not to save the items</field>
    this.productId = productId;
    this.productName = productName;
    this.updateDate = updateDate;
    this.saveItems = saveItems;
}

您会在此处获得对象的智能感知（它将显示您放置在returns元素中的内容）：

setProductAsPreviewed(

如果您决定创建一个新对象，您会在此处获得 IntelliSense（它将逐一显示每个参数的描述，随着您添加它们）：

setProductAsPreviewed(new ProductPreviewArgs(

我不确定在returns元素上使用type属性是否会像那样起作用，它在VS2012中确实可以，正如你现在可能已经期望的那样，这方面的文档令人恼火地简单； 而且我现在没有VS2010副本来测试任何内容。

- Sean Airey

---

感谢您的努力，Sean，但这并没有帮助到我。我有一个自定义对象，其中包含公共函数，我需要智能感知来支持它们。此外，我不想更改函数的签名，我想保留单个参数对象。 - Rui Jarimba

不知道你可以指定一个特定类型的数组参数/返回值 - 智能感应真是太棒了！ - andrewb

Answer 2

您可以创建一个单独的 IntelliSense 文件，其内容类似于以下内容：

intellisense.annotate(Content, {
  'setProductAsPreviewed ': function() {
    /// <signature>
    ///   <summary>Summary<summary>
    ///   <param name="args" type="ComplexObject">some text here
    /// </signature>
   }
})

我相信在进行一些修改后，这应该可以正常工作。

- Johan