Merge pull request #18059 from komakai:improve-swift-docs

modules/core/misc/objc/common/Mat.h

@@ -23,7 +23,19 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
-* The class Mat represents an n-dimensional dense numerical single-channel or multi-channel array.
+ The class Mat represents an n-dimensional dense numerical single-channel or multi-channel array.
+ ####Swift Example
+ ```swift
+ let mat = Mat(rows: 2, cols: 3, type: CvType.CV_8U)
+ try! mat.put(row: 0, col: 0, data: [2, 3, 4, 4, 5, 6] as [Int8])
+ print("mat: \(mat.dump())")
+ ```
+ ####Objective-C Example
+ ```objc
+ Mat* mat = [[Mat alloc] initWithRows:2 cols:3 type: CV_8U];
+ [m1 put:0 col:0 data:@[@2, @3, @4, @3, @4, @5]];
+ NSLog(@"mat: %@", [m1 dump]);
+ ```
 */
 CV_EXPORTS @interface Mat : NSObject
 
@@ -40,6 +52,12 @@ CV_EXPORTS @interface Mat : NSObject
 + (instancetype)fromNativePtr:(cv::Ptr<cv::Mat>)nativePtr;
 + (instancetype)fromNative:(cv::Mat&)nativeRef;
 #endif
+/**
+ Creates a Mat object with the specified number of rows and columns and Mat type
+ @param rows Number of rows
+ @param cols Number of columns
+ @param type Mat type (refer: `CvType`)
+*/
 - (instancetype)initWithRows:(int)rows cols:(int)cols type:(int)type;
 - (instancetype)initWithRows:(int)rows cols:(int)cols type:(int)type data:(NSData*)data;
 - (instancetype)initWithRows:(int)rows cols:(int)cols type:(int)type data:(NSData*)data step:(long)step;

modules/objc/generator/gen_objc.py

@@ -716,7 +716,7 @@ class ObjectiveCWrapperGenerator(object):
         namespace = self.classes[cname].namespace if self.classes.has_key(cname) else "cv"
         return namespace.replace(".", "::") + "::"
 
-    def gen(self, srcfiles, module, output_path, output_objc_path, common_headers):
+    def gen(self, srcfiles, module, output_path, output_objc_path, common_headers, manual_classes):
         self.clear()
         self.module = module
         self.Module = module.capitalize()
@@ -751,6 +751,7 @@ class ObjectiveCWrapperGenerator(object):
                     self.add_enum(decl)
                 else: # function
                     self.add_func(decl)
+        self.classes[self.Module].member_classes += manual_classes
 
         logging.info("\n\n===== Generating... =====")
         package_path = os.path.join(output_objc_path, module)
@@ -1243,6 +1244,7 @@ def copy_objc_files(objc_files_dir, objc_base_path, module_path, include = False
         if (not os.path.exists(dest)) or (os.stat(src).st_mtime - os.stat(dest).st_mtime > 1):
             copyfile(src, dest)
             updated_files += 1
+    return objc_files
 
 def unescape(str):
     return str.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
@@ -1298,6 +1300,7 @@ def sanitize_documentation_string(doc, type):
         .replace("@param[in]", "@param") \
         .replace("@param[out]", "@param") \
         .replace("@ref", "REF:") \
+        .replace("@note", "NOTE:") \
         .replace("@returns", "@return") \
         .replace("@sa ", "@see ") \
         .replace("@snippet", "SNIPPET:") \
@@ -1422,12 +1425,14 @@ if __name__ == "__main__":
             module_imports += gen_type_dict.get("module_imports", [])
 
         objc_files_dir = os.path.join(misc_location, 'common')
+        copied_files = []
         if os.path.exists(objc_files_dir):
-            copy_objc_files(objc_files_dir, objc_base_path, module, True)
+            copied_files += copy_objc_files(objc_files_dir, objc_base_path, module, True)
+
         if args.target == 'ios':
             ios_files_dir = os.path.join(misc_location, 'ios')
             if os.path.exists(ios_files_dir):
-                copy_objc_files(ios_files_dir, objc_base_path, module, True)
+                copied_files += copy_objc_files(ios_files_dir, objc_base_path, module, True)
 
         objc_test_files_dir = os.path.join(misc_location, 'test')
         if os.path.exists(objc_test_files_dir):
@@ -1436,8 +1441,12 @@ if __name__ == "__main__":
             if os.path.exists(objc_test_resources_dir):
                 copy_tree(objc_test_resources_dir, os.path.join(objc_test_base_path, 'test', 'resources'))
 
+        manual_classes = filter(lambda x:type_dict.has_key(x),
+                                map(lambda x: x[x.rfind('/')+1:-2],
+                                    filter(lambda x: x.endswith('.h'), copied_files)))
+
         if len(srcfiles) > 0:
-            generator.gen(srcfiles, module, dstdir, objc_base_path, common_headers)
+            generator.gen(srcfiles, module, dstdir, objc_base_path, common_headers, manual_classes)
         else:
             logging.info("No generated code for module: %s", module)
     generator.finalize(objc_base_path)

modules/objc/generator/templates/cmakelists.template

@@ -42,18 +42,3 @@ set_target_properties(opencv_objc_framework PROPERTIES
     PUBLIC_HEADER "$${objc_headers}"
     DEFINE_SYMBOL CVAPI_EXPORTS
     )
-
-find_program(JAZZY jazzy)
-
-if(JAZZY)
-    add_custom_command(
-        OUTPUT  "$${BUILD_ROOT}/modules/objc/doc_build/doc/index.html"
-        COMMAND $${JAZZY}  --objc --author OpenCV --author_url http://opencv.org --github_url https://github.com/opencv/opencv --umbrella-header "$${BUILD_ROOT}/lib/$${CMAKE_BUILD_TYPE}/$framework.framework/Headers/$framework.h" --framework-root "$${BUILD_ROOT}/lib/$${CMAKE_BUILD_TYPE}/$framework.framework" --module $framework --sdk iphonesimulator --undocumented-text \"\"
-        WORKING_DIRECTORY "$${BUILD_ROOT}/modules/objc/doc_build"
-        COMMENT "Generating Documentation"
-    )
-    add_custom_target(opencv_objc_doc ALL DEPENDS "$${BUILD_ROOT}/modules/objc/doc_build/doc/index.html")
-    add_dependencies(opencv_objc_doc opencv_objc_framework)
-else()
-    message("jazzy not found - documentation will not be generated!")
-endif()