Skip to content

Commit 99353aa

Browse files
odrobnikodrobnik
committed
Added appledoc documentation
1 parent e35a05c commit 99353aa

File tree

8 files changed

+309
-7
lines changed

8 files changed

+309
-7
lines changed

‎AppledocSettings.plist‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3+
<plist version="1.0">
4+
<dict>
5+
<key>--project-name</key>
6+
<string>DTLocalizableStringScanner</string>
7+
<key>--project-company</key>
8+
<string>Cocoanetics</string>
9+
<key>--project-version</key>
10+
<string>1.0</string>
11+
<key>--company-id</key>
12+
<string>com.cocoanetics</string>
13+
<key>--docset-atom-filename</key>
14+
<string>DTLocalizableStringScanner.atom</string>
15+
<key>--docset-feed-url</key>
16+
<string>https://docs.cocoanetics.com/DTLocalizableStringScanner/%DOCSETATOMFILENAME</string>
17+
<key>--docset-package-url</key>
18+
<string>https://docs.cocoanetics.com/DTLocalizableStringScanner/%DOCSETPACKAGEFILENAME</string>
19+
<key>--docset-fallback-url</key>
20+
<string>https://docs.cocoanetics.com/DTLocalizableStringScanner/</string>
21+
<key>--create-docset</key>
22+
<true/>
23+
<key>--publish-docset</key>
24+
<true/>
25+
<key>--install-docset</key>
26+
<false/>
27+
<key>--logformat</key>
28+
<string>xcode</string>
29+
<key>--keep-intermediate-files</key>
30+
<true/>
31+
<key>--no-repeat-first-par</key>
32+
<true/>
33+
<key>--ignore</key>
34+
<array>
35+
<string>*.m</string>
36+
<string>Core/Externals</string>
37+
<string>Demo</string>
38+
</array>
39+
<key>--index-desc</key>
40+
<string>Readme.markdown</string>
41+
<key>--warn-invalid-crossref</key>
42+
<false/>
43+
</dict>
44+
</plist>

‎Core/Source/DTLocalizableStringAggregator.h‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,53 @@
99
#import <Foundation/Foundation.h>
1010
#import "DTLocalizableStringEntry.h"
1111

12+
/**
13+
An aggregator that parses one or more source files and aggregates the results in multiple string tables.
14+
15+
You use this be calling beginProcessingFile: for each file. This starts the parsing thread for each file. Then you call aggregatedStringTables which blocks until all files are fully parsed.
16+
*/
17+
1218
@interface DTLocalizableStringAggregator : NSObject
1319

20+
/**
21+
@name Getting Information about the Aggregator
22+
*/
23+
24+
/**
25+
If set to `YES` then placeholders are numbered
26+
*/
1427
@property (nonatomic, assign) BOOL wantsPositionalParameters;
28+
29+
/**
30+
The encoding to use for interpreting the input files
31+
*/
1532
@property (nonatomic, assign) NSStringEncoding inputEncoding;
33+
34+
/**
35+
The names of the string tables to ignore.
36+
*/
1637
@property (nonatomic, retain) NSSet *tablesToSkip;
38+
39+
/**
40+
The custom macro prefix to use instead of NSLocalizedString.
41+
*/
1742
@property (nonatomic, retain) NSString *customMacroPrefix;
18-
@property (nonatomic, retain) NSString *defaultTableName;
1943

44+
/**
45+
@name Scanning Files
46+
*/
47+
48+
/**
49+
Begins processing a source code file
50+
@param fileURL The file URL of the code file to process
51+
*/
2052
- (void)beginProcessingFile:(NSURL *)fileURL;
2153

22-
// returns an array of DTLocalizableStringTables
23-
// blocks until all enqueued files have been processed
24-
- (NSArray *)aggregatedStringTables;
54+
/**
55+
Retrieves the string tables resulting from the parsing process
56+
@note blocks until all enqueued files have been processed
57+
@return An array of DTLocalizableStringTables
58+
*/
59+
- (NSArray *)aggregatedStringTables;
2560

2661
@end

‎Core/Source/DTLocalizableStringEntry.h‎

Lines changed: 57 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,77 @@
1010

1111
@class DTLocalizableStringEntry;
1212

13+
/**
14+
An entry in a string table
15+
*/
16+
1317
@interface DTLocalizableStringEntry : NSObject
1418

19+
/**
20+
@name Getting Information about Entries
21+
*/
22+
23+
/**
24+
The raw key as it was found in the original file
25+
*/
1526
@property (nonatomic, copy) NSString *rawKey;
27+
28+
/**
29+
The raw value as it was found in the original file
30+
*/
1631
@property (nonatomic, copy) NSString *rawValue;
32+
33+
/**
34+
The name of the table that this entry belongs to
35+
*/
1736
@property (nonatomic, copy) NSString *tableName;
37+
38+
/**
39+
The bundle name that this entry belongs to
40+
*/
1841
@property (nonatomic, copy) NSString *bundle;
1942

43+
/**
44+
The contents of the rawKey with escape sequences removed
45+
*/
2046
@property (nonatomic, readonly) NSString *cleanedKey;
47+
48+
/**
49+
The contents of the rawValue with escape sequences removed
50+
*/
2151
@property (nonatomic, readonly) NSString *cleanedValue;
2252

23-
- (void)setComment:(NSString *)comment; // for KVC
53+
/**
54+
@name Working with Comments
55+
*/
56+
57+
/**
58+
Removes all existing comments and sets a single one.
59+
@param comment The comment to set.
60+
*/
61+
- (void)setComment:(NSString *)comment;
2462

63+
/**
64+
Appends the comment to the receiver's list of comments
65+
@param comment The comment to add.
66+
*/
2567
- (void)addComment:(NSString *)comment;
68+
69+
/**
70+
An alphabetically sorted list of comments. This property is cached internally.
71+
@returns The sorted comments
72+
*/
2673
- (NSArray *)sortedComments;
2774

28-
// used for output sorting
75+
/**
76+
@name Sorting Entries
77+
*/
78+
79+
/**
80+
Compares the receiver against another entry. This is used for output sorting.
81+
@param otherEntry The other entry to compare against
82+
@return An `NSComparisonResult`
83+
*/
2984
- (NSComparisonResult)compare:(DTLocalizableStringEntry *)otherEntry;
3085

3186
@end

‎Core/Source/DTLocalizableStringScanner.h‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,27 @@
1212

1313
typedef void(^DTLocalizableStringEntryFoundCallback)(DTLocalizableStringEntry *);
1414

15+
/**
16+
Source Code scanner operation, based on `NSOperation`. Scans a a source file and emits an entryFoundCallback whenever a new localized string Macro is encountered.
17+
*/
18+
1519
@interface DTLocalizableStringScanner : NSOperation
1620

21+
/**
22+
@name Creating a Scanner
23+
*/
24+
25+
/**
26+
Creates a source scanner operation.
27+
@param url The file URL of the file to scan
28+
@param encoding The string encoding of the source file
29+
@param validMacros The macro prototypes that are considered valid
30+
*/
1731
- (id)initWithContentsOfURL:(NSURL *)url encoding:(NSStringEncoding)encoding validMacros:(NSDictionary *)validMacros;
1832

33+
/**
34+
The callback to execute for each found macro.
35+
*/
1936
@property (nonatomic, copy) DTLocalizableStringEntryFoundCallback entryFoundCallback;
2037

2138
@end

‎Core/Source/DTLocalizableStringTable.h‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,69 @@
1212

1313
typedef void(^DTLocalizableStringEntryWriteCallback)(DTLocalizableStringEntry *);
1414

15+
16+
/**
17+
Class representing a strings table. A strings table consists of key value pairs which are represented by DTLocalizableStringEntry instances.
18+
*/
19+
1520
@interface DTLocalizableStringTable : NSObject
1621

22+
/**
23+
@name Getting Information
24+
*/
25+
26+
/**
27+
Name of the String Table
28+
*/
1729
@property (nonatomic, readonly) NSString *name;
30+
31+
/**
32+
Whether the receiver should decode unicode sequences
33+
*/
1834
@property (nonatomic, assign) BOOL shouldDecodeUnicodeSequences;
1935

36+
/**
37+
@name Creating a String Table
38+
*/
39+
40+
/**
41+
Creates a new string table with a given name
42+
@param name The name of the string table
43+
*/
2044
- (id)initWithName:(NSString *)name;
2145

46+
/**
47+
@name Modifying the String Table
48+
*/
49+
50+
/**
51+
Appends a new string table entry to the receiver
52+
@param entry The new entry to add
53+
*/
2254
- (void)addEntry:(DTLocalizableStringEntry *)entry;
2355

56+
57+
/**
58+
@name Creating Output
59+
*/
60+
61+
/**
62+
Creates a textual representation of the string table
63+
@param encoding The output string encoding
64+
@param error If an error occurs it will be output via this parameter
65+
@param entryWriteCallback The block to execute before an entry is output
66+
@returns An `NSString ` containing the contents of the receiver
67+
*/
2468
- (NSString *)stringRepresentationWithEncoding:(NSStringEncoding)encoding error:(NSError **)error entryWriteCallback:(DTLocalizableStringEntryWriteCallback)entryWriteCallback;
69+
70+
/**
71+
Writes a textual representation of the string table into a file
72+
@param url The file URL to write to
73+
@param encoding The output string encoding
74+
@param error If an error occurs it will be output via this parameter
75+
@param entryWriteCallback The block to execute before an entry is output
76+
@returns An `NSString ` containing the contents of the receiver
77+
*/
2578
- (BOOL)writeToFolderAtURL:(NSURL *)url encoding:(NSStringEncoding)encoding error:(NSError **)error entryWriteCallback:(DTLocalizableStringEntryWriteCallback)entryWriteCallback;
2679

2780
@end

‎Core/Source/DTLocalizableStringsParser.h‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,39 +9,54 @@
99

1010
@class DTLocalizableStringsParser;
1111

12+
/**
13+
Delegate protocol that informs a DTLocalizableStringsParser delegate about parsing events.
14+
*/
1215
@protocol DTLocalizableStringsParserDelegate <NSObject>
1316

1417
@optional
18+
/**
19+
@name Parsing Events
20+
*/
1521

1622
/**
1723
Sent to the delegate for each comment block found
24+
@param parser The strings parser
25+
@param comment The comment that was found
1826
*/
1927
- (void)parser:(DTLocalizableStringsParser *)parser foundComment:(NSString *)comment;
2028

2129
/**
2230
Sent to the delegate for each comment block found
31+
@param parser The strings parser
32+
@param key The key that was found
33+
@param value The value that was found
2334
*/
2435
- (void)parser:(DTLocalizableStringsParser *)parser foundKey:(NSString *)key value:(NSString *)value;
2536

2637
/**
2738
Sent to the delegate once parsing has finished
39+
@param parser The strings parser
2840
*/
2941
- (void)parserDidStartDocument:(DTLocalizableStringsParser *)parser;
3042

3143
/**
3244
Sent to the delegate once parsing has finished
45+
@param parser The strings parser
3346
*/
3447
- (void)parserDidEndDocument:(DTLocalizableStringsParser *)parser;
3548

3649
/**
3750
Sent to the delegate if an error occurs
51+
@param parser The strings parser
52+
@param parseError The parsing error
3853
*/
3954
- (void)parser:(DTLocalizableStringsParser *)parser parseErrorOccurred:(NSError *)parseError;
4055

4156
@end
4257

4358
/**
44-
Parser for strings files. You initialize it with a file URL, set a delegate and start parsing with parse. This returns `YES` in case of success.
59+
Parser for strings files. You initialize it with a file URL, set a delegate and execute parsing with parse.
4560
*/
4661
@interface DTLocalizableStringsParser : NSObject
4762

@@ -51,6 +66,7 @@ Sent to the delegate once parsing has finished
5166

5267
/**
5368
Instantiates a strings file parser
69+
@param url The file URL for the file to parse
5470
*/
5571
- (id)initWithFileURL:(NSURL *)url;
5672

@@ -60,6 +76,7 @@ Sent to the delegate once parsing has finished
6076

6177
/**
6278
Parses the file.
79+
@returns `YES` if parsing was successful.
6380
*/
6481
- (BOOL)parse;
6582

‎Core/Source/NSString+DTLocalizableStringScanner.h‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,42 @@
88

99
#import <Foundation/Foundation.h>
1010

11+
/**
12+
Helper methods for string parsing
13+
*/
1114
@interface NSString (DTStringFileParser)
1215

16+
/**
17+
@name Modifying Strings
18+
*/
19+
20+
/**
21+
Adds format placeholder numbering to the receiver
22+
@returns A new string with placeholders numbered
23+
*/
1324
- (NSString *)stringByNumberingFormatPlaceholders;
1425

26+
/**
27+
Determine predicate variations
28+
@returns An array with all predicate variations
29+
*/
1530
- (NSArray *)variantsFromPredicateVariations;
1631

32+
/**
33+
Decodes unicode sequences found in the receiver
34+
@returns The decoded string
35+
*/
1736
- (NSString *)stringByDecodingUnicodeSequences;
1837

38+
/**
39+
Replaces slash escapes with the original characters
40+
@returns The receiver with slash-escapes replaced
41+
*/
1942
- (NSString *)stringByReplacingSlashEscapes;
43+
44+
/**
45+
Escapes control characters with slash escapes
46+
@returns The receiver's content with control characters slash-escaped
47+
*/
2048
- (NSString *)stringByAddingSlashEscapes;
2149
@end

0 commit comments

Comments
 (0)