Generate TypeScript comments in TypeScript declarations

[ivanbuhov]

First merge: NativeScript/ios-metadata-generator#37

TypeScript declarations look like this:

Function:

    /**
     * Creates and returns a new instance of a given class.
     * @param aClass - The class of which to create an instance.
     * @param extraBytes - The number of extra bytes required for indexed instance variables (this value is typically 0).
     * @param zone - The zone in which to create the new instance (pass NULL to specify the default zone).
     */
    declare function NSAllocateObject(aClass: typeof NSObject, extraBytes: number, zone: interop.Pointer): any;

Constant:

    /**
     * All directories where resources can occur.
     */
    declare const NSAllLibrariesDirectory: number;

Interface (with static method, instance method and property):

    /**
     * NSArray and its subclass NSMutableArray manage ordered collections of objects called arrays. NSArray creates static arrays, and NSMutableArray creates dynamic arrays. You can use arrays when you need an ordered collection of objects.
     */
    declare class NSArray<ObjectType> extends NSObject implements CKRecordValue, NSCopying, NSFastEnumeration, NSMutableCopying, NSSecureCoding {

        /**
         * Returns a new instance of the receiving class.
         */
        static alloc<ObjectType>(): NSArray<ObjectType>; // inherited from NSObject

        /**
         * Returns a new array that is a copy of the receiving array with a given object added to the end.
         * @param anObject - An object.
         */
        arrayByAddingObject(anObject: ObjectType): NSArray<ObjectType>;

        /**
         * The number of objects in the array.
         */
        /* readonly */ count: number;

Protocol:

    /**
     * The delegate of an NSCache object implements this protocol to perform specialized actions when an object is about to be evicted or removed from the cache.
     */
    interface NSCacheDelegate extends NSObjectProtocol {

        /**
         * Called when an object is about to be evicted or removed from the cache.
         * @param cache - The cache with which the object of interest is associated.
         * @param obj - The object of interest in the cache.
         */
        cacheWillEvictObject?(cache: NSCache<any, any>, obj: any): void;
    }

Struct:

    /**
     * An audio file region specifies a segment of audio data.
     */
    interface AudioFileRegion {
        /**
         * A unique ID associated with the audio file region.
         */
        mRegionID: number;
        /**
         * The name of the region.
         */
        mName: string;
        /**
         * Audio File Services region flags. For details, see Audio File Region Flags.
         */
        mFlags: AudioFileRegionFlags;
        /**
         * The number of markers in the array specified in the  mMarkers parameter.
         */
        mNumberMarkers: number;
        /**
         * An array of mNumberMarkers elements describing where the data in the region starts. For details, see Audio File Marker Types.
         */
        mMarkers: interop.Reference<AudioFileMarker>;
    }

Enum:

    declare const enum AudioFileStreamPropertyFlags {

        /**
         * This flag is set when the callback AudioFileStream_PropertyListenerProc is invoked in the case that the value of the property has been cached and can be obtained later.
         */
        kAudioFileStreamPropertyFlag_PropertyIsCached = 1,

        /**
         * A property listener sets this flag to instruct the parser to cache the property value so that it remains available after the callback returns.
         */
        kAudioFileStreamPropertyFlag_CacheProperty = 2
    }

[ihor-lev]

Hi guys! I'm getting syntax warnings on this + there is a typo mistake in effective_platofrm_name. Seems that it's a python version dependent. I have python 3.8.3 today.

./build-step-metadata-generator.py:57: SyntaxWarning: "is" with a literal. Did you mean "=="?
  if effective_platofrm_name is "-macosx":
./build-step-metadata-generator.py:59: SyntaxWarning: "is" with a literal. Did you mean "=="?
  elif effective_platofrm_name is "-watchos" or effective_platofrm_name is "-watchsimulator":
./build-step-metadata-generator.py:59: SyntaxWarning: "is" with a literal. Did you mean "=="?
  elif effective_platofrm_name is "-watchos" or effective_platofrm_name is "-watchsimulator":
./build-step-metadata-generator.py:61: SyntaxWarning: "is" with a literal. Did you mean "=="?
  elif effective_platofrm_name is "-appletvos" or effective_platofrm_name is "-appletvsimulator":
./build-step-metadata-generator.py:61: SyntaxWarning: "is" with a literal. Did you mean "=="?
  elif effective_platofrm_name is "-appletvos" or effective_platofrm_name is "-appletvsimulator":

UPD: Just realized that fixing it with a "==" helped me to run an ipa build. I was fighting for days with that:

** ARCHIVE FAILED **

Command xcodebuild failed with exit code 65

Thanks!