XCode文档注释

使用Xcode的User Scripts可以很方便的为代码添加注释，方法如下

 

整行选中下面的代码，因为默认的Insert @method template脚本解析的问题，你需要保证+/-号后面有一个空格，否则插入注释时会出现问题。

1	+ (NSData *) captureScreenWithSize:(CGSize) captureSize atView:(UIView*)view;

选择HeaderDoc中的Insert @method template脚本，即可方便的插入脚本，插入代码大致如下

 

 

同样，我们可以生成其他代码注释，如header,class,protocol等。

我们可以修改默认的Insert @method template脚本，让其支持+ (NSData *)这样中间没有空格的情况。方法如下

选择Edit User Scripts…

 

打开Insert @method template，将其中的代码替换为如下代码

 

01	#! /usr/bin/perl -w

02

#

03	# Inserts a template HeaderDoc comment for an

04	# Objective-C method.

05	# If the user selects a method declaration and

06	# chooses this command, the template includes

07	# the method name and the names of each parameter.

08	# If the user doesn't select a declaration before issuing

09	# this command, a default template is inserted.

10

11	use strict;

12

13	my $selection = <<'SELECTION';

14	%%%{PBXSelectedText}%%%

15

SELECTION

16	chomp $selection;

17	my $unmodifiedSelection = $selection; # used to retain linebreaks in output

18

19	$selection =~ s/\n/ /sg;     # put on one line, if necessary

20	$selection =~ s/\s+$//;      # remove any trailing spaces

21	$selection =~ s/\s{2,}/ /g;  # regularize remaining spaces

22

23	my $displayMethodName= '';

24	my $returnsAValue= 0;

25	my @params = ();

26

27	# is it a method declaration that we understand?

28	if (length($selection) && ($selection =~ /^[+-]/) && ($selection =~ /;$/)) {

29	# determine if it returns a value

30	$selection =~ m/[+-]\s*(\((.*?)\))?\s*(.*);/;

31	my $return = $2;

32	my $fullMethodName = $3;

33	if ((defined($return)) && ($return ne 'void') && ($returnne 'IBAction')) {$returnsAValue=1;};

34

35	if (defined($fullMethodName)) {

36	# get rid of type info for args

37	$fullMethodName =~ s/\(.*?\)//g;

38

39	if ($fullMethodName =~ /:/) {

40	# get keyword:arg pairs

41	my @keyArgPairs = split(/\s+/, $fullMethodName);

42

43	foreach my $pair (@keyArgPairs) {

44	if ($pair =~ /:/) { # don't treat parameters with spaces as method names

45	my @parts = split(/:/, $pair);

46	while (@parts) {

47	$displayMethodName .= shift(@parts).":";

48	push (@params, shift @parts);

49

}

50

} else {

51	if (length($pair)) { # but do add them to the parameter list

52	push (@params, $pair);

53

}

54

}

55

}

56

} else {

57	$displayMethodName = $fullMethodName;

58

}

59

}

60

}

61

62	print "/*!\n";

63	print "    \@method     $displayMethodName\n";

64	print "    \@abstract   %%%{PBXSelection}%%%<#(brief description)#>%%%{PBXSelection}%%%\n";

65	print "    \@discussion <#(comprehensive description)#>\n";

66

67	foreach my $param (@params) {

68	print "    \@param      $param <#(description)#>\n" if (defined($param));

69

}

70

71	print "    \@result     <#(description)#>\n" if ($returnsAValue);

72	print "*/\n";

73	print $unmodifiedSelection;

74

75

exit 0;

 另外，HeaderDoc中没有提供给property插入注释的代码, 我们可以加入如下代码来实现给property添加注释 

01	#! /usr/bin/perl -w

02	# Insert HeaderDoc template for class

03	# by xeonwell

04	use strict;

05

06	my $selection = <<'SELECTION';

07	%%%{PBXSelectedText}%%%

08

SELECTION

09	chomp $selection;

10	my $unmodifiedSelection = $selection;

11	$selection =~ s/\n/ /sg;     # put on one line, if necessary

12	$selection =~ s/\s+$//;      # remove any trailing spaces

13	$selection =~ s/\s{2,}/ /g;  # regularize remaining spaces

14	$selection =~ s/;$//;

15

16	my @params = split(/\s/, $selection);

17	my $pname = $params[scalar(@params)-1];

18	$pname =~ s/^\*//;

19

20	print "/*!\n";

21	print "    \@property $pname\n";

22	print "    \@abstract %%%{PBXSelection}%%%<#(brief description)#>%%%{PBXSelection}%%%\n";

23	print "*/\n";

24	print $unmodifiedSelection;

25

exit 0;

为了比较方便的插入文档注释， 我们还可以为这些脚本设置快捷键，当选中需要添加注释的method、property等时，直接按快捷键即可。

完成这些步骤之后，使用如下的方法来生成我们需要的注释

方法一：开启一个终端，然后切换到项目所在文件夹，运行如下命令

1	headerdoc2html –o hdoc *.h

2	gatherheaderdoc hdoc

方法二：使用doxygen来生成文档， 参考地址

http://www.stack.nl/~dimitri/doxygen/manual.html

参考文档：http://huajun.w18.net/?p=205