add doxygen for core lib and ammend documentation

README.md

@@ -1,26 +1,30 @@
 ###Strings
 =======
 
-Strings is an utility to transform and manage the diffrent localization files from and to an iOS project and an Android project.
-The obejctive-C project has 2 targets. They are meant for managing strings through an GUI interface as well as a command line one.
+Strings is an utility to transform and manage the diffrent localization files from and to an iOS project and an Android project.<br>
+The obejctive-C project has 2 targets. They are meant for managing strings through an GUI interface as well as a command line one.<br>
 
 The core library at the moment is 
 - Transforming both iOS and Android translation files into Dictionaries
 - Grouping together the same transaltions file from different language folders
 - Grouping together iOS and Android files with the same keys in it (match >= 5).
-- On conversion between the platforms will also take care of formats specific changes (%@ -> $1@ ...)
+- On conversion between the platforms will also take care of format specific convertions (%@ -> $1@ ...)
 
 
 ###Documentations
-Documentation is a bit behind, also the code is purely commented. I promise to add doxigen as soon as possible.
-There are however only 4 classes worth mentioning, which are the one doing mosto fo the heavy lifting to aggregate and translate the files.
-Those are:
+There are 4 classes part of the core library, which are the one doing most of the heavy lifting to aggregate and translate the files.<br>
+Those are:<br>
 
 - ZFLangFile - Rapresentation of a language file, contaninng all the languages translations for both iOS and Android
 - ZFStringScanner - goes through all the forlders form a given root one and generates the ZFLangFiles
 - ZFStringsConverter - Feed with a URL of a string file will generate the dicotionary of transaltions. Also will reconvert a dictionary to iOS or Android file given a URL. It is used by ZFLanfFile to generate the translations
 - ZFUtils - Singletons with commons tasks. Pretty empty at the moment
 
+Doxygen documentation is present for those 4 classes. The rest of the documentation will come later.
 
 ###Tests
 Tests are a bit behind
+
+### Aknolegment
+My background comes from iOS developemnt. In that sense I feel pretty confident with the import/export and translation of the files. However this project could really use some help from some more experienced Mac OS X developers to address the user interface, as well as some Android developers ot check the format conversion and the parsing of xml files.<br>
+At this stage the basic for file conversion is at a good stage. Most important features to be implemented are the keeping the order of the keys during parsing comapred with original files, and consequently tracking and parsing of the comments inside the files (at the moment both ignored). Also the Andorid xml string elements sometimes contain a format attribute that is ignored from the covnertion and later on the parsing as well.<br>

Strings/ZFLangFile.m

@@ -31,6 +31,17 @@ - (id)init {
     return self;
 }
 
+
+/*!
+ @abstract
+ Generate a list of minimum 5 keys to be used for comparison
+ 
+ @return NSArray of keys
+ 
+ @discussion The method will first look at allKeys, then if missing or too small, will try to get them from either iOStranslation or androidTRanslations.
+ 
+ */
+
 - (NSArray *)hashKeys {
     if (!_hashKeys) {
 
@@ -60,6 +71,18 @@ - (BOOL)isEqual:(id)object {
 }
 
 
+/*!
+ @abstract
+ Preferred method to convert a file at URL to ZFLangFile
+ 
+ @param url of the file in the disk
+ 
+ @return YES if the operation of adding result succesfull No otherwise
+ 
+ @discussion This method covnert the url in a dictioanry of keys and transaltions to be addedd to the translations for the relative language identifier
+ 
+ */
+
 - (BOOL)addFileAtURL:(NSURL *)url {
     BOOL isIOS;
     NSString *lang = [[ZFUtils sharedUtils] langFromURL:url isIOS:&isIOS];
@@ -87,6 +110,18 @@ - (BOOL)addFileAtURL:(NSURL *)url {
     return YES;
 }
 
+/*!
+ @abstract
+ Tries to merge a given file if and only if the there is amtch between the keys
+ 
+ @param file, the fiel to be merged
+ 
+ @return YES if the file have been merged, NO otherwise
+ 
+ @discussion The act of cross reference the keys and then merging the languages and the translations is expensive. Maybe need refactoring
+ 
+ */
+
 - (BOOL)mergeWithFile:(ZFLangFile *)file {
     if (![self isEqual:file]) return NO;
 
@@ -114,6 +149,14 @@ - (BOOL)mergeWithFile:(ZFLangFile *)file {
     return didMerge;
 }
 
+/*!
+ @abstract
+ Fill the blanks in languages and translation keys
+ 
+ @discussion Used to generate the getters for allKeys and allLanguages. Those two get constantly nilled by addFileAtURL and mergeWithFile, so they may become source of problems (dead loops in primis)
+ 
+ */
+
 - (void)fillGaps {
     NSMutableArray *allKeys = [NSMutableArray array];
     NSMutableArray *allLanguages = [NSMutableArray array];

Strings/ZFStringScanner.m

@@ -36,6 +36,14 @@ - (NSFileManager *)fileManager {
 
 #pragma mark - conversions
 
+/*!
+ @abstract
+ Scan the url for translations files for both iOS and Android
+ 
+ @param url of the resource
+ 
+ */
+
 - (void)scanAtURL:(NSURL *)URL {
 
     NSError *error = nil;
@@ -64,6 +72,16 @@ - (void)scanAtURL:(NSURL *)URL {
 
 }
 
+/*!
+ @abstract
+ Entry point for scanning recursively starting from a given URL
+ 
+ @param url, root of the scan to perform
+ 
+ @discussion After the directory scan is complete, all the generated files get merged by languages and resource type (iOS/Android)
+ 
+ */
+
 - (void)startScanAtURL:(NSURL *)URL {
     [self scanAtURL:URL];
 

Strings/ZFStringsConverter.h

@@ -10,8 +10,8 @@
 
 @interface ZFStringsConverter : NSObject
 
-- (void)convertStringsAtURL:(NSURL *)stringsURL toXMLAtURL:(NSURL *)XMLURL;
-- (void)convertXMLAtURL:(NSURL *)XMLURL toStringsAtURL:(NSURL *)stringsURL;
+- (void)convertStringsAtURL:(NSURL *)stringsURL toXMLAtURL:(NSURL *)XMLURL  __deprecated;
+- (void)convertXMLAtURL:(NSURL *)XMLURL toStringsAtURL:(NSURL *)stringsURL  __deprecated;
 
 
 - (NSDictionary *)translationsForXMLAtURL:(NSURL *)XMLURL;

Strings/ZFStringsConverter.m

@@ -12,6 +12,20 @@ @implementation ZFStringsConverter
 
 #pragma mark - Strings
 
+/*!
+ @abstract
+ Convert a string substituting the format value from and to iOS/Andorid
+ 
+ @param input string to be converted
+ 
+ @param isIOS boolean for the conversion direction
+ 
+ @return NSSTring, the converted string
+ 
+ @discussion The converter takes care of different string rapresentation and enumeration of arguaments on Andorid
+ 
+ */
+
 - (NSString *)convertFormatForString:(NSString *)input isIOS:(BOOL)isIOS {
     static NSRegularExpression *formatIOSRegEx;
     static NSRegularExpression *formatAndroidRegEx;
@@ -38,6 +52,18 @@ - (NSString *)convertFormatForString:(NSString *)input isIOS:(BOOL)isIOS {
     return (NSString *)mutValue;
 }
 
+/*!
+ @abstract
+ Convert the .strings file at a given URL and converts it to a dictionary of transaltions
+ 
+ @param stringsURL the url of the file to be converted
+ 
+ @return NSDictionary with the translations
+ 
+ @discussion The comments are not recorded so they are lost in this fase already. The same is true for the key sorting which is likely to become alphabetical in the process
+ 
+ */
+
 - (NSDictionary *)translationsForStringsAtURL:(NSURL *)stringsURL {
 
     if (!stringsURL) return nil;
@@ -65,6 +91,16 @@ - (NSDictionary *)translationsForStringsAtURL:(NSURL *)stringsURL {
 
 }
 
+/*!
+ @abstract
+ Parse the dictionary of translations to a string ready to be written to a .strings file
+ 
+ @param dictionary of translations
+ 
+ @return NSString ready in .strings format
+ 
+ */
+
 - (NSString *)stringsStringFromDictionary:(NSDictionary *)dictionary {
 
     NSMutableString *stringsString = [NSMutableString string];
@@ -79,6 +115,18 @@ - (NSString *)stringsStringFromDictionary:(NSDictionary *)dictionary {
 
 #pragma mark - XML
 
+/*!
+ @abstract
+ Converts the .xml file at URL to a dictionary of translations
+ 
+ @param MLXURL of the file to be converted
+ 
+ @return NSDictionary with the translations
+ 
+ @discussion This doesn't take care of the format parameter found in some xml translation files
+ 
+ */
+
 - (NSDictionary *)translationsForXMLAtURL:(NSURL *)XMLURL {
     NSMutableDictionary *translation = [NSMutableDictionary dictionary];
     NSError *error = nil;
@@ -95,6 +143,18 @@ - (NSDictionary *)translationsForXMLAtURL:(NSURL *)XMLURL {
     return (NSDictionary *)translation;
 }
 
+/*!
+ @abstract
+ Parse the dictionary of transaltions to a string ready to be written on an .xml file
+ 
+ @param dictionary with the transaltions
+ 
+ @return NSString ready to be written to an .xml file
+ 
+ @discussion The format attribute is not parsed as not tracked
+ 
+ */
+
 - (NSString *)xmlStringFromDictionary:(NSDictionary *)dictionary {
 
     NSMutableArray *elements = [NSMutableArray array];
@@ -116,7 +176,7 @@ - (NSString *)xmlStringFromDictionary:(NSDictionary *)dictionary {
 
 #pragma mark - Converters
 
-- (void)convertStringsAtURL:(NSURL *)stringsURL toXMLAtURL:(NSURL *)XMLURL {
+- (void)convertStringsAtURL:(NSURL *)stringsURL toXMLAtURL:(NSURL *)XMLURL __deprecated{
     NSDictionary *translations = [self translationsForStringsAtURL:stringsURL];
     NSString *translationsString = [self xmlStringFromDictionary:translations];
 
@@ -125,7 +185,7 @@ - (void)convertStringsAtURL:(NSURL *)stringsURL toXMLAtURL:(NSURL *)XMLURL {
 }
 
 
-- (void)convertXMLAtURL:(NSURL *)XMLURL toStringsAtURL:(NSURL *)stringsURL {
+- (void)convertXMLAtURL:(NSURL *)XMLURL toStringsAtURL:(NSURL *)stringsURL  __deprecated{
     NSDictionary *translations = [self translationsForXMLAtURL:XMLURL];
     NSString *translationsString = [self stringsStringFromDictionary:translations];
 

Strings/ZFUtils.h

@@ -16,3 +16,4 @@
 +(ZFUtils *)sharedUtils;
 
 @end
+

Strings/ZFUtils.m

@@ -17,6 +17,7 @@ @interface ZFUtils ()
 
 @implementation ZFUtils
 
+#pragma mark Getters
 
 - (NSRegularExpression *)iOSLangRegEx {
     if (!_iOSLangRegEx) {
@@ -34,6 +35,18 @@ - (NSRegularExpression *)androidLangRegEx {
     return _androidLangRegEx;
 }
 
+#pragma mark - Lang utils
+
+/*!
+ @abstract
+ Checks the URL path for the language identifier and recognise if it's and iOS or Andorid path
+ 
+ @param url, the url to be checked
+ @param iuIOS, reference to the boolean that will be changed accordingly
+ @return NSSTring with the language identifier. Ex: en, it, de, fr, es ...
+ 
+ */
+
 
 - (NSString *)langFromURL:(NSURL *)url isIOS:(BOOL *)isIOS {
     NSArray *matches = [self.iOSLangRegEx matchesInString:url.absoluteString options:NSMatchingReportCompletion range:NSMakeRange(0, url.absoluteString.length)];
@@ -52,7 +65,7 @@ - (NSString *)langFromURL:(NSURL *)url isIOS:(BOOL *)isIOS {
     return lang;
 }
 
-#pragma mark singleton
+#pragma mark - singleton
 
 static ZFUtils *_sharedUtils;