iOSSystemFrameworks注释标准

如何分工协作?

• ①首先从进度.h文件确认文件编号,例如编号fileNumber
• ②在源库下会有54个子分支,根据从上一步中的fileNumber值确定属于哪一个分支,计算公式为:分支号branchNumber= (fileNumber+49)/50. 然后从54个子分支列表.md获取要提交的库链接,例如为linkOfNoX.
  这54个分支代表的意义如下图所示

分工图.png

如何提交修改?

登录github
->在上面获得的linkOfNoX界面下点击右上角的fork,复制一份代码到自己的库中
->在自己复制的库中进行各种修改
->将修改提交到自己复制的库中
->在code界面点击New pull request
->再点击create new pull request,填写相关注释信息
->此时再点击create pull request,即可将修改提交到源库
->剩下的就是在我这边合并修改了

注释标准

以UIAlertView.h为例所有括号中的信息皆为说明作用

①紧接头部原有注释添加维护者信息,维护者联系邮箱,以及该文件对应的详细解释. 如果发生维护交接的情况,则将原有的维护者信息移到文件末尾,然后写上新维护者的信息.

//
//  UIAlertView.h
//  UIKit
//
//  Copyright 2010-2012 Apple Inc. All rights reserved.
//
/*
 * 由XXX维护
 * 联系邮箱:XXXX@xxx.xxx
 * 本文件对应维护地址:xxxxx(网址,网址中的资料务求详尽实用)
 */

#import 
#import 
#import 
#import 

②考虑到未来要替换系统原有库,以及便于合并.注释要在不影响原有代码作用的前提下单独占一行或多行

NS_ASSUME_NONNULL_BEGIN

typedef NS_ENUM(NSInteger, UIAlertViewStyle) {
    //注释在不影响原有代码效果的情况下独占n行,以避免在合并时发生冲突
    UIAlertViewStyleDefault = 0,
    /*也可以写成
     多行注释形式,总之以安全高效,实用美观为标准*/
    UIAlertViewStyleSecureTextInput,
    UIAlertViewStylePlainTextInput,
    UIAlertViewStyleLoginAndPasswordInput
} __TVOS_PROHIBITED;

③保留代码原有格式,例如保留的空行要前后一致

- (id)initWithFrame:(CGRect)frame NS_DESIGNATED_INITIALIZER;
- (nullable instancetype) initWithCoder:(nonnull NSCoder *)aDecoder NS_DESIGNATED_INITIALIZER;

//保留原有代码行间隔,比如这里有一行空行,那填上注释后仍要保留空行
@property(nullable,nonatomic,weak) id /**/ delegate;
//保留原有代码行间隔,比如这里原来没有空行,那填上注释后也没有空行
@property(nonatomic,copy) NSString *title;
@property(nullable,nonatomic,copy) NSString *message;   // secondary explanation text

④原有英文注释要保留,可是视情况对英文注释做翻译,要紧贴代码

@property(nullable,nonatomic,copy) NSString *message;   // secondary explanation text


// adds a button with the title. returns the index (0 based) of where it was added. buttons are displayed in the order added except for the
// cancel button which will be positioned based on HI requirements. buttons cannot be customized.
//保留系统原有英文注释;中文注释可以在翻译英文注释基础上丰富
//中文注释紧邻代码
- (NSInteger)addButtonWithTitle:(nullable NSString *)title;    // returns index of button. 0 based.
- (nullable NSString *)buttonTitleAtIndex:(NSInteger)buttonIndex;
@property(nonatomic,readonly) NSInteger numberOfButtons;

⑤多参数方法可以借助VVDocument插件来生成标准注释

// Retrieve a text field at an index
// The field at index 0 will be the first text field (the single field or the login field), the field at index 1 will be the password field. */
/**
 *  多参数的可以借助vvDocument插件来写标准注释
 *
 *  @param textFieldIndex 参数意义及使用
 *
 *  @return 返回值
 */
- (nullable UITextField *)textFieldAtIndex:(NSInteger)textFieldIndex NS_AVAILABLE_IOS(5_0);


@end

整体注释效果

//
//  UIAlertView.h
//  UIKit
//
//  Copyright 2010-2012 Apple Inc. All rights reserved.
//
/*
 * 由XXX维护
 * 联系邮箱:XXXX@xxx.xxx
 * 本文件对应维护地址:xxxxx(网址,网址中的资料务求详尽实用)
 */

#import 
#import 
#import 
#import 

NS_ASSUME_NONNULL_BEGIN

typedef NS_ENUM(NSInteger, UIAlertViewStyle) {
    //注释在不影响原有代码效果的情况下独占n行,以避免在合并时发生冲突
    UIAlertViewStyleDefault = 0,
    /*也可以写成
     多行注释形式,总之以安全高效,实用美观为标准*/
    UIAlertViewStyleSecureTextInput,
    UIAlertViewStylePlainTextInput,
    UIAlertViewStyleLoginAndPasswordInput
} __TVOS_PROHIBITED;

@protocol UIAlertViewDelegate;
@class UILabel, UIToolbar, UITabBar, UIWindow, UIBarButtonItem, UIPopoverController;

NS_CLASS_DEPRECATED_IOS(2_0, 9_0, "UIAlertView is deprecated. Use UIAlertController with a preferredStyle of UIAlertControllerStyleAlert instead") __TVOS_PROHIBITED
@interface UIAlertView : UIView

- (instancetype)initWithTitle:(nullable NSString *)title message:(nullable NSString *)message delegate:(nullable id /**/)delegate cancelButtonTitle:(nullable NSString *)cancelButtonTitle otherButtonTitles:(nullable NSString *)otherButtonTitles, ... NS_REQUIRES_NIL_TERMINATION NS_EXTENSION_UNAVAILABLE_IOS("Use UIAlertController instead.");

- (id)initWithFrame:(CGRect)frame NS_DESIGNATED_INITIALIZER;
- (nullable instancetype) initWithCoder:(nonnull NSCoder *)aDecoder NS_DESIGNATED_INITIALIZER;

//保留原有代码行间隔,比如这里有一行空行,那填上注释后仍要保留空行
@property(nullable,nonatomic,weak) id /**/ delegate;
//保留原有代码行间隔,比如这里原来没有空行,那填上注释后也没有空行
@property(nonatomic,copy) NSString *title;
@property(nullable,nonatomic,copy) NSString *message;   // secondary explanation text


// adds a button with the title. returns the index (0 based) of where it was added. buttons are displayed in the order added except for the
// cancel button which will be positioned based on HI requirements. buttons cannot be customized.
//保留系统原有英文注释;中文注释可以在翻译英文注释基础上丰富
//中文注释紧邻代码
- (NSInteger)addButtonWithTitle:(nullable NSString *)title;    // returns index of button. 0 based.
- (nullable NSString *)buttonTitleAtIndex:(NSInteger)buttonIndex;
@property(nonatomic,readonly) NSInteger numberOfButtons;
@property(nonatomic) NSInteger cancelButtonIndex;      // if the delegate does not implement -alertViewCancel:, we pretend this button was clicked on. default is -1

@property(nonatomic,readonly) NSInteger firstOtherButtonIndex;  // -1 if no otherButtonTitles or initWithTitle:... not used
@property(nonatomic,readonly,getter=isVisible) BOOL visible;

// shows popup alert animated.
- (void)show;

// hides alert sheet or popup. use this method when you need to explicitly dismiss the alert.
// it does not need to be called if the user presses on a button
- (void)dismissWithClickedButtonIndex:(NSInteger)buttonIndex animated:(BOOL)animated;

// Alert view style - defaults to UIAlertViewStyleDefault
@property(nonatomic,assign) UIAlertViewStyle alertViewStyle NS_AVAILABLE_IOS(5_0);

// Retrieve a text field at an index
// The field at index 0 will be the first text field (the single field or the login field), the field at index 1 will be the password field. */
/**
 *  多参数的可以借助vvDocument插件来写标准注释
 *
 *  @param textFieldIndex 参数意义及使用
 *
 *  @return 返回值
 */
- (nullable UITextField *)textFieldAtIndex:(NSInteger)textFieldIndex NS_AVAILABLE_IOS(5_0);


@end

__TVOS_PROHIBITED
@protocol UIAlertViewDelegate 
@optional

// Called when a button is clicked. The view will be automatically dismissed after this call returns
- (void)alertView:(UIAlertView *)alertView clickedButtonAtIndex:(NSInteger)buttonIndex NS_DEPRECATED_IOS(2_0, 9_0);

// Called when we cancel a view (eg. the user clicks the Home button). This is not called when the user clicks the cancel button.
// If not defined in the delegate, we simulate a click in the cancel button
- (void)alertViewCancel:(UIAlertView *)alertView NS_DEPRECATED_IOS(2_0, 9_0);

- (void)willPresentAlertView:(UIAlertView *)alertView NS_DEPRECATED_IOS(2_0, 9_0);  // before animation and showing view
- (void)didPresentAlertView:(UIAlertView *)alertView NS_DEPRECATED_IOS(2_0, 9_0);  // after animation

- (void)alertView:(UIAlertView *)alertView willDismissWithButtonIndex:(NSInteger)buttonIndex NS_DEPRECATED_IOS(2_0, 9_0); // before animation and hiding view
- (void)alertView:(UIAlertView *)alertView didDismissWithButtonIndex:(NSInteger)buttonIndex NS_DEPRECATED_IOS(2_0, 9_0);  // after animation

// Called after edits in any of the default fields added by the style
- (BOOL)alertViewShouldEnableFirstOtherButton:(UIAlertView *)alertView NS_DEPRECATED_IOS(2_0, 9_0);

@end

NS_ASSUME_NONNULL_END