To rename a project'sfolder,file(.*proj) anddisplay namein Visual Studio:
Close the solution.
Rename the folder(s) outside Visual Studio. (Rename in TFS if using source control)
Open the solution, ignoring the warnings (answer "no" if asked to load a project from source control).
Go through all the unavailable projects and...
Open the properties window for the project (highlight the project and press Alt+Enter or F4, or right-click > properties).
Set the property 'File Path' to the new location.
If the property is not editable (as in Visual Studio 2012), then open the .sln file directly in another editor such as Notepad++ and update the paths there instead. (You may need to check-out the solution first in TFS, etc.)
Reload the project - right-click > reload project.
Change the display name of the project, by highlighting it and pressing F2, or right-click > rename.
Note: Other suggested solutions that involve removing and then re-adding the project to the solution will break project references.
If you perform these steps then you might also consider renaming the following to match:
Assembly
Default/Root Namespace
Namespace of existing files (use the refactor tools in Visual Studio or ReSharper's inconsistent namespaces tool)
Short descriptions should be clear, simple, and brief. Document “what” and “when” – “why” should rarely need to be included. The “why” can go in the long description if needed. For example:
Functions and closures are third-person singular elements, meaning third-person singular verbs should be used to describe what each does.
Tip:Need help remembering how to conjugate for third-person singular verbs? Imagine prefixing the function, hook, class, or method summary with “It”:
Good: “(It) Does something.”
Bad: “(It) Do something.”
Functions: What does the function do?
Good: Handles a click on X element.
Bad: Included for back-compat for X element.
@since: The recommended tool to use when searching for the version something was added to WordPress is svn blame.
If, after using these tools, the version number cannot be determined, use @since Unknown.
Code Refactoring: Do not refactor code in the file when changes to the documentation.
Descriptive elements should be written as complete sentences. The one exception to this standard is file header summaries, which are intended as file “titles” more than sentences.
The serial (Oxford) comma should be used when listing elements in summaries, descriptions, and parameter or return descriptions.
The following guidelines should be followed to ensure that the content of the doc blocks can be parsed properly for inclusion in the code reference.
Short descriptions:
Short descriptions should be a single sentence and contain no markup of any kind. If the description refers to an HTML element or tag, then it should be written as “link tag”, not “<a>”. For example: “Fires when printing the link tag in the header”.
Long descriptions:
Markdown can be used, if needed, in a long description.
@param and @return tags:
No HTML or markdown is permitted in the descriptions for these tags. HTML elements and tags should be written as “audio element” or “link tag”.
DocBlock text should wrap to the next line after 80 characters of text. If the DocBlock itself is indented on the left 20 character positions, the wrap could occur at position 100, but should not extend beyond a total of 120 characters wide.
Summary: A brief, one line explanation of the purpose of the function. Use a period at the end.
Description: A supplement to the summary, providing a more detailed description. Use a period at the end.
@deprecated x.x.x: Only use for deprecated functions, and provide the version the function was deprecated which should always be 3-digit (e.g. @since 3.6.0), and the function to use instead.
@since x.x.x: Should be 3-digit for initial introduction (e.g. @since 3.6.0). If significant changes are made, additional @since tags, versions, and descriptions should be added to serve as a changelog.
@access: Only use for functions if private. If the function is private, it is intended for internal use only, and there will be no documentation for it in the code reference.
@class: Use for class constructors.
@augments: For class constuctors, list direct parents.
@mixes: List mixins that are mixed into the object.
@alias: If this function is first assigned to a temporary variable this allows you to change the name it’s documented under.
@memberof: Namespace that this function is contained within if JSDoc is unable to resolve this automatically.
@static: For classes, used to mark that a function is a static method on the class constructor.
@see: A function or class relied on.
@link: URL that provides more information.
@fires: Event fired by the function. Events tied to a specific class should list the class name.
@listens: Events this function listens for. An event must be prefixed with the event namespace. Events tied to a specific class should list the class name.
@global: Marks this function as a global function to be included in the global namespace.
@param: Give a brief description of the variable; denote particulars (e.g. if the variable is optional, its default) with JSDoc @param syntax. Use a period at the end.
@yield: For generator functions, a description of the values expected to be yielded from this function. As with other descriptions, include a period at the end.
@return: Note the period after the description.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
/**
* Summary. (use period)
*
* Description. (use period)
*
* @since x.x.x
* @deprecated x.x.x Use new_function_name() instead.
* @access private
*
* @class
* @augments parent
* @mixes mixin
*
* @alias realName
* @memberof namespace
*
* @see Function/class relied on
* @link URL
* @global
*
* @fires eventName
* @fires className#eventName
* @listens event:eventName
* @listens className~event:eventName
*
* @param {type} var Description.
* @param {type} [var] Description of optional variable.
* @param {type} [var=default] Description of optional variable with default variable.
* @param {Object} objectVar Description.
* @param {type} objectVar.key Description of a key in the objectVar parameter.
Backbone’s extend calls should be formatted as follows:
@lends This tag will allow JSDoc to recognize the extend function from Backbone as a class definition. This should be placed right before the Object that contains the class definition.
Backbone’s initialize functions should be formatted as follows:
Summary: A brief, one line explanation of the purpose of the function. Use a period at the end.
Description: A supplement to the summary, providing a more detailed description. Use a period at the end.
@deprecated x.x.x: Only use for deprecated classes, and provide the version the class was deprecated which should always be 3-digit (e.g. @since 3.6.0), and the class to use instead.
@since x.x.x: Should be 3-digit for initial introduction (e.g. @since 3.6.0). If significant changes are made, additional @since tags, versions, and descriptions should be added to serve as a changelog.
@constructs Marks this function as the constructor of this class.
@augments: List direct parents.
@mixes: List mixins that are mixed into the class.
@requires: Lists modules that this class requires. Multiple @requires tags can be used.
@alias: If this class is first assigned to a temporary variable this allows you to change the name it’s documented under.
@memberof: Namespace that this class is contained within if JSDoc is unable to resolve this automatically.
@static: For classes, used to mark that a function is a static method on the class constructor.
@see: A function or class relied on.
@link: URL that provides more information.
@fires: Event fired by the constructor. Should list the class name.
@param: Document the arguments passed to the constructor even if not explicitly listed in initialize. Use a period at the end.
Backbone Models are passed attributes and options parameters.
Backbone Views are passed an options parameter.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Class = Parent.extend( /** @lends namespace.Class.prototype */{
/**
* Summary. (use period)
*
* Description. (use period)
*
* @since x.x.x
* @deprecated x.x.x Use new_function_name() instead.
* @access private
*
* @constructs namespace.Class
* @augments Parent
* @mixes mixin
*
* @alias realName
* @memberof namespace
*
* @see Function/class relied on
* @link URL
* @fires Class#eventName
*
* @param {Object} attributes The model's attributes.
* @param {type} attributes.key One of the model's attributes.
* @param {Object} [options] The model's options.
* @param {type} attributes.key One of the model's options.
*/
initialize: function() {
//Do stuff.
}
} );
If a Backbone class does not have an initialize function it should be documented by using @inheritDoc as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/**
* Summary. (use period)
*
* Description. (use period)
*
* @since x.x.x
* @deprecated x.x.x Use new_function_name() instead.
* @access private
*
* @constructs namespace.Class
* @memberOf namespace
* @augments Parent
* @mixes mixin
* @inheritDoc
*
* @alias realName
* @memberof namespace
*
* @see Function/class relied on
* @link URL
*/
Class = Parent.extend( /** @lends namespace.Class.prototype */{
// Functions and properties.
} );
Note: This currently doesn’t provide the expected functionality due to a bug with JSDoc’s inheritDoc tag. See the issue here
At times classes will have Ancestors that are only assigned to a local variable. Such classes should be assigned to the namespace their children are and be made inner classes using ~.
@since x.x.x: Should be 3-digit for initial introduction (e.g. @since 3.6.0). If significant changes are made, additional @since tags, versions, and descriptions should be added to serve as a changelog.
@access: If the members is private, protected or public. Private members are intended for internal use only.
@type: List the type of the class member.
@property List all properties this object has in case it’s an Object. Use a period at the end.
@member: Optionally use this to override JSDoc’s member detection in place of @type to force a class member.
@memberof: Optionally use this to override what class this is a member of.
@namespace: Marks this symbol as a namespace, optionally provide a name as an override.
@since x.x.x: Should be 3-digit for initial introduction (e.g. @since 3.6.0). If significant changes are made, additional @since tags, versions, and descriptions should be added to serve as a changelog.
@memberof: Namespace that this namespace is contained in.
@property: Properties that this namespace exposes. Use a period at the end.
I realize this is new, but I found some errors. It’s great that this page exists now.
“@global: List JavaScript globals that are used within the function, with an optional description of the global.” This is incorrect usage of the @global tag in JSDoc. To quote the JSDoc docs (no pun intended), “Use the @global tag to specify that a symbol should be documented as global.” See http://usejsdoc.org/tags-global.html
The example under Functions is incorrect when it comes to @param and @return. The type should be in braces, and optional parameters are specified by surrounding the name with brackets (in JSDoc style). It should be:
I realize this is new, but I found some errors. It’s great that this page exists now.
“@global: List JavaScript globals that are used within the function, with an optional description of the global.”
This is incorrect usage of the @global tag in JSDoc. To quote the JSDoc docs (no pun intended), “Use the @global tag to specify that a symbol should be documented as global.” See http://usejsdoc.org/tags-global.html
The example under Functions is incorrect when it comes to @param and @return. The type should be in braces, and optional parameters are specified by surrounding the name with brackets (in JSDoc style). It should be:
*/
or:
*/
Lastly, the style given for block comments differs from the one on the coding standards page: https://make.wordpress.org/core/handbook/coding-standards/javascript/#comments.The style on this page matches the PHP one, however. Which should be used?
source : https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/