onevcat / vvdocumenter-xcode

Xcode plug-in which helps you write documentation comment easier, for both Objective-C and Swift.

VVDocumenter-Xcode

---

Goodbye World

In Xcode 8, Apple integrated a comment documentation generator plugin, which is built on top of VVDocumenter. Now this project is proud to be a part of Apple. It means you could just use the shortcut (⌥ Option + ⌘ Command + /) to add a documentation comment to your code if you are using Xcode 8 or above!

VVDocumenter is one of my hobby projects from 2013, back to the age of Xcode 4. It serves well for these years and I am so glad that it helps a lot of developers to improve their productivity. Since there is no need to install this plugin anymore, the development of VVDocumenter will not continue. Yes, it's time to say goodbye, with a happy ending.

Thank you all for your selfless support to this project. Let's build more great things and make the world better in future!

What is this?

Writing documentation is so important for developing, but it is really painful with Xcode. Think about how much time you are wasting in pressing '*' or '/', and typing the parameters again and again. Now, you can find the method (or any code) you want to document to, and type in ///, the document will be generated for you and all params and return will be extracted into a Javadoc style, which is compatible with appledoc, Doxygen and HeaderDoc. You can just fill the inline placeholder tokens to finish your document.

Here is an image which can show what it exactly does.

By the way, it also supports Swift now. Cheers!

How to install and use?

The best way of installing is by Alcatraz. Install Alcatraz followed by the instruction, restart your Xcode and press ⇧⌘9. You can find VVDocumenter-Xcode in the list and click the icon on left to install.

If you do not like the Alcatraz way, you can also clone the repo. Then build the VVDocumenter-Xcode target in the Xcode project and the plug-in will automatically be installed in ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins. Relaunch Xcode and type in /// above any code you want to write a document to.

If you want to use other text beside of /// to trigger the document insertion, you can find a setting panel by clicking VVDocument in the Window menu of Xcode. You can also find some other useful options there, including setting using spaces instead of tab in the panel or changing the format of generated documentation.

Xcode version?

This plug-in is supported in Xcode 5, 6 and 7. From Xcode 5, Apple added a UUID-verification to all plugins to ensure the stability when Xcode gets updated. The value of DVTPlugInCompatibilityUUIDs in project plist should contains current UUID of Xcode version, or the plugin does not work. And from Xcode 6.3, you will be prompt to "Load third party bundle" if you are using a plugin. You should always select "Load bundles" to enable this plugin.

All plugins will be disabled once you update your Xcode, since the supported UUIDs in the plugins do not contain the one. You should try to clean your plugins folder (~/Library/Application Support/Developer/Shared/Xcode/Plug-ins by default) and clone/build the latest version from master branch. If you happened to skip the bundle loading, you can use this to reset the prompt:

defaults delete com.apple.dt.Xcode DVTPlugInManagerNonApplePlugIns-Xcode-{your_xcode_version}

Please do not open an issue if this plugin not work in your newly updated Xcode. Pull request for new DVTPlugInCompatibilityUUIDs is welcome, and if UUID of your Xcode version is already there, please try to reinstall the plugin from a clean state.

The default deployment target is 10.8. If you want to use it in a earlier OS version, you should change OS X Deployment Target (in project info setting) to your system version.

Swift Support

Yes, this plugin supports documentation for Swift 2 now. Check this post to see how to write the documentation for swift. By using VVDocumenter-Xcode, you can just type /// to make the magic happen.

The documentation format changed from Swift 1.x to 2. If you are using Swift 1.x, you could build from branch Xcode6 to get the support for the earlier format.

Limitations and Future

The plugin is using simulation of keyboard event to insert the doc comments for you. So it is depending the keyboard shortcut of Xcode. These two kinds of operation are being used:

• Delete to Beginning of the Line (⌘⌫)
• Paste (⌘V)

If you have modified these two shortcuts in your Xcode, the newset version of the plugin would not work correctly. Instead, you can use a earlier version such as this one(commit 03c4169ff7). Be causion you may suffer an undo and redo issue .

VVDocumenter-Xcode is now using regular expression to extract things needed, which is not the best way to do such thing. A better approach could be using the AST, and I also have a plan to do it later if I have some more time :)

License

VVDocumenter is published under MIT License. See the LICENSE file for more.

vvdocumenter-xcode's Issues

Redundant @return when using `virtual` keyword in C++.

See codes:

Correct one:

/**
 *  <#Description#>
 */
void a();

Wrong one:

/**
 *  <#Description#>
 *
 *  @return <#return value description#>
 */
virtual void a();

"Prefix each comment line with a star" is ignored in Swift files.

I have "Prefix each comment line with a star" selected in the VVDocumenter config, but when I trigger VVDocumenter in a Swift file, it prefixes the documentation with whitespace only.

我安装您的插件失败了，提示权限不足（I failed to install your plug , suggesting insufficient permissions）

Specific information is as follows
/bin/mkdir -p /Users/wanghuanqiang/Library/Application\ Support/Developer/Shared/Xcode/Plug-ins/VVDocumenter-Xcode.xcplugin/Contents
error: Unable to create directory: /Users/wanghuanqiang/Library/Application Support/Developer/Shared/Xcode/Plug-ins/VVDocumenter-Xcode.xcplugin/Contents (Permission denied)

Not working with non standard keyboard layout

Hello,

I have a non standard keyboard layout. I create forward slashes with alt+s for example. With this configuration the three slashes just flash quickly and disappear. I am suggesting that this should be documented in the README or that the insertion of that the blocks should work with any layout. I have not built plugins for Xcode, but is there no way to insert strings into the buffer without emulating the keyboard?

Don't working on Xcode 5.1

I updated my Xcode to version 5.1, and than I installed VVDocumenter, but it isn't working :(

PS.: I didn't have it installed.

is there a concept of internal?

headerdoc2html has a concept of @internal in that it will not build docs for these fields/headers unless you explicitly flag that you want them.

i'm building a framework for clients to implement, some files are public, some are private, some are project... obviously i'm looking to only export the public headers instead of everything as is the default... is there any way to go about this in a 'proper' way?(short of deleting html files after it all gets generated...)

goal: i'd like to have the option of building the private documentation for my side for us to use internally, and i'd like to be able to build documentation that i can ship with my framework.

How to set the Enter？

I want to set Trigger Input as "// enter" .The "enter" is a really Keyboard events.

How to set the Enter？

Thank you!

inline block params

Inserts an objective C style comment for some swift functions

When I /// above the subscript function in the sample below, it inserts an obj-c style comment block.

public class Issue <KeyType, ValueType>
{
public subscript (key: KeyType) -> ValueType?
{
var value: ValueType? = nil
return value
}
}

Bug with comment text indent

I'm using XCode 5.1.1 (5B1008), my comment text created by VVDocumenter look like:

In "ScreenShot.gif" it seems like that the indent is correct.

I'm using default VVDocumenter preferences.

Return tuple components appearing as method parameters

In the example below, the variables product and max are being incorrectly document as method parameters.

    ///  <#Description#>
    ///
    ///  :param: a       <#a description#>
    ///  :param: b       <#b description#>
    ///  :param: c       <#c description#>
    ///  :param: product <#product description#>
    ///  :param: max     <#max description#>
    ///
    ///  :returns: <#return value description#>
    func makeTuple(a:Int, b:Int, c:Int) -> (sum:Int, product:Int, max:Int) {
            return (a + b + c, a * b * c, max(a, b, c))
    }

Regards,
Vince.

Support var arguments in Swift functions

Swift supports making a mutable copy of an argument by prefixing its name with var.

However, VVDocumenter fails to parse the function signature when using this feature.

/**
<#Description#>

:param: a <#a description#>
*/
func testA<A>(a: A) {}

/// <#Description#>
func testB<B>(var b: B) {}

It seems the c++ constructor and destructor are not supported.

not works in Xcode5

I clone the project and build, restart my project, then type ///, it doesn't work at all.
What's missing?

Setting window cannot be accessed in Xcode 6 GM Seed

I am using Xcode 6 GM Seed, and when I try to click on the VVDocumenter option in the Window menu, nothing happens, no window is displayed, so I have no way to access settings. Help! Thx.

Get rid of * stars along side of multiline comment

These stars are actually stopping the @code directive from being reconised in xcode is there a way to configure VVDocumenter to not do this so

/*

• @param hi
  */

Becomes:

/*
@param hi
*/

Programmer Dvorak keyboard layout

在升级到Xcode5.1并且使用Programmer Dvorak keyboard layout之后，插件就用不了了。
开始一直以为是升级带来的问题折腾半天，没辙看了下源码原来是键盘布局问题。

• if ([layoutID isEqualToString:@"com.apple.keylayout.Dvorak"])
• if ([layoutID rangeOfString:@"Dvorak" options:NSCaseInsensitiveSearch].length > 0)
  改了就好了

用一些奇葩布局还是要付出代价的。。。

Warning: Unknown command tag name 'Author'; did you mean 'author'?

Getting compiler warning when building with CLANG_WARN_DOCUMENTATION_COMMENTS: Yes.

"Unknown command tag name 'Author'; did you mean 'author'?"

你好，这个插件Xcode5底下不可用

没找到解决方法，特来请教~

Crash on typedef NS_ENUM

Plugin crashes when you type "///" above "typedef NS_ENUM"

For example:

/// # This is where it crashes
typedef NS_ENUM(NSInteger, SMDatePeriod)
{
SMDatePeriodDaily = 0,
SMDatePeriodWeekly,
SMDatePeriodMonthly,
SMDatePeriodYearly,
SMDatePeriodCustom
};

Not giving method comments on typing /// .

Not giving "FORMATTED COMMENTING" on typing /// .Its giving Last copied text. Even though rebuild with latest VVDocumenter getting same issue.

/// comment variation

per this:
http://nshipster.com/documentation/

///---------------------------------------
/// @name Accessing HTTP Client Properties
///---------------------------------------

I know you can change the trigger, but seems like a bad default.

Wrong @param when argument default value is given in C++

See the codes:

virtual void run(RegridMethod method, int timeLevel, const RLLVelocityField &f,
                 const SpaceCoord &x, SphereVelocity &y, RLLMeshIndex *idx = NULL);

and the output of VVDocument-Xcode:

/**
     *  <#Description#>
     *
     *  @param method    <#method description#>
     *  @param timeLevel <#timeLevel description#>
     *  @param f         <#f description#>
     *  @param x         <#x description#>
     *  @param y         <#y description#>
     *  @param NULL      <#NULL description#>
     *
     *  @return <#return value description#>
     */

the last argument is not NULL but idx.

Does not work on xCode 4.6.3 / Mac OSX 10.7.5

Hello!

I've tried to install this plugin on my development notebook running MAC OSX 10.7.5 and xCode 4.6.3. the plugin itself is created in ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins. But! when i try to add /// nothing happens in the code editor window.

What I am doing wrong ?

Thank you in advance

Cocoa pods?

Are there any plans to make a cocoa pod? I would love to drop this into my podfile for every project rather than reintegrating the repo

No @return generated if return type is void *

Steps to reproduce:

• Create a function prototype that returns a pointer to void, e.g. void *foo(void);
• InvokeVV with ///

Expected:

• Documentation is generated with an @return statement

Actual:

• No return statement is generated in the documentation

Swift - External Parameter Name Ignored

When adding a documentation to a function that has parameters that include both an external parameter name and a local parameter name, the external name should be the one used in the @param line, but the local name is the one presented. For example:

///  <#Description#>
///
///  :param: L <#L description#>
///  :param: G <#G description#>
///
///  :returns: <#return value description#>
func eclipticLongitude(meanLongitude L:Double, meanAnomaly G:Double) -> Double {
    return L + 1.915 * sinD(G) + 0.02 * sinD(2 * G)
}

This should be:

///  <#Description#>
///
///  :param: meanLongitude <#meanLongitude description#>
///  :param: meanAnomaly <#meanAnomaly description#>
///
///  :returns: <#return value description#>
func eclipticLongitude(meanLongitude L:Double, meanAnomaly G:Double) -> Double {
    return L + 1.915 * sinD(G) + 0.02 * sinD(2 * G)
}

build failed

Can't build with 10.10 Base SDK (10.9 is OK) in Xcode 6.1

Change the Base SDK to 10.9 can successful build and install the plugin. 😄

Don't know if this can say a bug. 🐛

Undo and Redo bug

There is a bug when you do some "undo" and "redo" operations while leaving the inline placeholder of document comment unfilled. It might be something wrong related to string range calculation. See Discussion section below for more.

How to reproduce

Be sure to use a test file to do it.

1. Type in /// above any code you want to do a documentation. Comment lines with at least one inline placeholder will be generated as usual.
2. Do not fill that placeholder, move your cursor below to a new line of code you want to document with. Type in /// to generate a new doc comment.
3. Press Cmd+Z to do undo operations, until everything goes back to the initial state.
4. Then press Shift+Cmd+Z to redo twice. You will see the bug. You are not getting the right redo result as expected.

Discussion

A method of DVTSourceTextStorage (which is a subclass of NSTextStorage used by the Xcode editor) named replaceCharactersInRange:withString:withUndoManager: is used for replacing the typed in /// to the doc comments. It works well in Xcode 4 unless you try to do some redo operations with the docs. When doing redo, the line range's location can not be accessed correctly, due to a <# #> tag is being generating while creating the docs. After added, Xcode editor will recognize these tags as inline place holder and convert the <# #> (including the content between two #) to a DVTTextFoldInlineTokenAttachment object and set it to the attributes to the DVTSourceTextStorage (which is a subclass NSAtrributedString).

The converted token only takes 1 length in the DVTSourceTextStorage, so there is a mismatch of redo's range location and real needed range location. When you do a redo, the inserting place is wrong.

I am not familiar with NSTextView and NSUndoManager. I have tried other strategies like paste board and replace the attributed string directly. But all were without luck.

And as described in the Readme file, the undo manager is not working for Xcode 5 DP now. I guess the implement of replaceCharactersInRange:withString:withUndoManager: is changed. I will keep an eye on the newer release of Xcode 5 and see what I can do.

Solve

Solved in tag 0.2. See comment below.

Broken on XCode 5 GM?

Having issues getting VVDocumenter to work on XCode 5 GM. Nothing happens when typing the triple slashes. Plugin on the right directory (double checked).

Also I'm getting a warning:
****/VVDocumenter-Xcode/VVDocumenter-Xcode.xcodeproj Garbage Collection is deprecated; use the "Convert to Objective-C ARC" menu command to switch to Automatic Reference Counting

inline block params no longer being documented (reopen #8)

I've just built the latest version on Xcode 5.1.1 and on Mavericks 10.9.2

In this version inline block comments are not being generated. e.g: from any signature whether the block is the only parameter or one of a larger number of parameters.

I saw that this issue was recored as fixed #8, but I didn't know how to re-open it, I don't think I can.

Questions about typedef Block

Like this block, I think no need to add @return and @param void.
Is this a bug?

插件不支持xcode6

你好，你的这个插件现在不支持xcode6。

typedef block params

@since automatically include current version number

Hello!
Can you add the following functions:
When I use @SInCE, the plugin can automatically use the current version like <#1.1#>.

Thank you.

仅致敬

一直不知道是个国人制造的,哈!Xcode 6.0.1不能用了后来找原因,然后下载源码编译,看到已经有了Xcode6的DVTPlugInCompatibilityUUIDs,于是编译看看,原来2个月前你就做了兼容!真是用心了!

致敬你的工作!另外我把这个插件的见识放在我的见识上:http://see.sl088.com/wiki/Xcode%E6%8F%92%E4%BB%B6_VVDocumenter

另外的,我想开启这个issues,除了表达致敬外,我想是否可以打包个release支持Xcode6的呢,因为看起来是最后一个打包还是许久前的.

Setting Panel does not show in Xcode 6.0.1 (6A317)

Click "Window" --> "VVDocumenter". Nothing is shown.
The package was installed via Alcatraz.

Support extension comments

Per the very popular Ray Wenderlich style guide, extensions should be commented like so:

// MARK: - UITableViewDelegate
extension SomeViewController: UITableViewDelegate {
}

Can you modify the /// expansion so that if it's looking at an extension that includes a delegate then it puts the MARK there with the single leading - character?

无法正确列出参数

定义函数void print2DList(int rowCount, int (*p)[10]);
只能列出参数p。
另外，这两个参数交换位置，也是只列出参数p。

Change default target to 10.9

Thanks for the awesome plug-in! Since Mavericks has been out for awhile, could you update default target to 10.9?

Thanks!

Alcatraz Support

Do you plan to add it to the https://github.com/mneorr/alcatraz-packages repository so it can be easily installed via alcatraz?

documentation above #define

Seems to miss variables when hitting /// above #define statements.

Example below it misses @param for self.frame.size.width

/**

• <#Description#>

• @param self.barMargin_2 <#self.barMargin_2 description#>

• @return <#return value description#>
  _/
  #define barWidth (self.frame.size.width - (self.barMargin_2))

Dvorak keyboard layout

Hi, I am currently using the dvorak keyboard layout, and the VVDocumenter plugin
doesn't seem to work. When I use the trigger input, the "Debug" on the menu bar blinks as if it were used.

I tried with the qwerty and the azerty keyboard layout and it worked fine.
I checked all my key binding, I even tested with all the default key binding, but
nothing changed.

I do not understand why it doesn't work with the dvorak layout.
I have the XCode version 5.0 and the OS 10.8.5.

Could you have a look at it ?

Thanks

Enum bug

Source code:

typedef NS_ENUM(Byte, IBLRegisterNetworkType) {

    IBLRegisterNetworkTypeError = 0x00,
    /**
     *    无线网络(WiFi)
     *
     *    @since 1.0.0.2
     */
    IBLRegisterNetworkTypeWireless = 0x01,
    /**
     *    有线网络
     *
     *    @since 1.0.0.2
     */
    IBLRegisterNetworkTypeWired = 0x02
};

Swift Support

This is a great plugin. Can't wait to use it to help document my Swift code.

Please update for production 6.1 Xcode

Block声明不能文档化

如果这样做,那么无法激活文档化
void (^devowelizer)(id, NSUInteger, BOOL *);

crash in 10.8.4 xcode 4.6

UNCAUGHT EXCEPTION (NSInvalidArgumentException): -[__NSCFString stringByReplacingRegexPattern:withString:]: unrecognized selector sent to instance 0x403ab5520

Support property/method grouping per @name

I'm not quite sure, if this can be automatically detected by VVDocumenter, but it would be great to create property/method-groups using the @name-property like described in http://nshipster.com/documentation/.

If no automation is possible, perhaps a secondary tag could be used (//* for example), to automatically insert the documentation stub.