iOSSystemFrameworks注釋標(biāo)準(zhǔn)

如何分工協(xié)作?

  • ①首先從進(jìn)度.h文件確認(rèn)文件編號(hào),例如編號(hào)fileNumber
  • ②在源庫(kù)下會(huì)有54個(gè)子分支,根據(jù)從上一步中的fileNumber值確定屬于哪一個(gè)分支,計(jì)算公式為:分支號(hào)branchNumber= (fileNumber+49)/50. 然后從54個(gè)子分支列表.md獲取要提交的庫(kù)鏈接,例如為linkOfNoX.
    這54個(gè)分支代表的意義如下圖所示
分工圖.png

如何提交修改?

登錄github
->在上面獲得的linkOfNoX界面下點(diǎn)擊右上角的fork,復(fù)制一份代碼到自己的庫(kù)中
->在自己復(fù)制的庫(kù)中進(jìn)行各種修改
->將修改提交到自己復(fù)制的庫(kù)中
->在code界面點(diǎn)擊New pull request
->再點(diǎn)擊create new pull request,填寫相關(guān)注釋信息
->此時(shí)再點(diǎn)擊create pull request,即可將修改提交到源庫(kù)
->剩下的就是在我這邊合并修改了

注釋標(biāo)準(zhǔn)

以UIAlertView.h為例所有括號(hào)中的信息皆為說(shuō)明作用

①緊接頭部原有注釋添加維護(hù)者信息,維護(hù)者聯(lián)系郵箱,以及該文件對(duì)應(yīng)的詳細(xì)解釋. 如果發(fā)生維護(hù)交接的情況,則將原有的維護(hù)者信息移到文件末尾,然后寫上新維護(hù)者的信息.


//
//  UIAlertView.h
//  UIKit
//
//  Copyright 2010-2012 Apple Inc. All rights reserved.
//
/*
 * 由XXX維護(hù)
 * 聯(lián)系郵箱:XXXX@xxx.xxx
 * 本文件對(duì)應(yīng)維護(hù)地址:xxxxx(網(wǎng)址,網(wǎng)址中的資料務(wù)求詳盡實(shí)用)
 */

#import <Foundation/Foundation.h>
#import <UIKit/UIKitDefines.h>
#import <UIKit/UITextField.h>
#import <UIKit/UIView.h>

②考慮到未來(lái)要替換系統(tǒng)原有庫(kù),以及便于合并.注釋要在不影響原有代碼作用的前提下單獨(dú)占一行或多行


NS_ASSUME_NONNULL_BEGIN

typedef NS_ENUM(NSInteger, UIAlertViewStyle) {
    //注釋在不影響原有代碼效果的情況下獨(dú)占n行,以避免在合并時(shí)發(fā)生沖突
    UIAlertViewStyleDefault = 0,
    /*也可以寫成
     多行注釋形式,總之以安全高效,實(shí)用美觀為標(biāo)準(zhǔn)*/
    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 /*<UIAlertViewDelegate>*/ delegate;
//保留原有代碼行間隔,比如這里原來(lái)沒(méi)有空行,那填上注釋后也沒(méi)有空行
@property(nonatomic,copy) NSString *title;
@property(nullable,nonatomic,copy) NSString *message;   // secondary explanation text

④原有英文注釋要保留,可是視情況對(duì)英文注釋做翻譯,要緊貼代碼


@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.
//保留系統(tǒng)原有英文注釋;中文注釋可以在翻譯英文注釋基礎(chǔ)上豐富
//中文注釋緊鄰代碼
- (NSInteger)addButtonWithTitle:(nullable NSString *)title;    // returns index of button. 0 based.
- (nullable NSString *)buttonTitleAtIndex:(NSInteger)buttonIndex;
@property(nonatomic,readonly) NSInteger numberOfButtons;

⑤多參數(shù)方法可以借助VVDocument插件來(lái)生成標(biāo)準(zhǔn)注釋


// 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. */
/**
 *  多參數(shù)的可以借助vvDocument插件來(lái)寫標(biāo)準(zhǔn)注釋
 *
 *  @param textFieldIndex 參數(shù)意義及使用
 *
 *  @return 返回值
 */
- (nullable UITextField *)textFieldAtIndex:(NSInteger)textFieldIndex NS_AVAILABLE_IOS(5_0);


@end

整體注釋效果

//
//  UIAlertView.h
//  UIKit
//
//  Copyright 2010-2012 Apple Inc. All rights reserved.
//
/*
 * 由XXX維護(hù)
 * 聯(lián)系郵箱:XXXX@xxx.xxx
 * 本文件對(duì)應(yīng)維護(hù)地址:xxxxx(網(wǎng)址,網(wǎng)址中的資料務(wù)求詳盡實(shí)用)
 */

#import <Foundation/Foundation.h>
#import <UIKit/UIKitDefines.h>
#import <UIKit/UITextField.h>
#import <UIKit/UIView.h>

NS_ASSUME_NONNULL_BEGIN

typedef NS_ENUM(NSInteger, UIAlertViewStyle) {
    //注釋在不影響原有代碼效果的情況下獨(dú)占n行,以避免在合并時(shí)發(fā)生沖突
    UIAlertViewStyleDefault = 0,
    /*也可以寫成
     多行注釋形式,總之以安全高效,實(shí)用美觀為標(biāo)準(zhǔn)*/
    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 /*<UIAlertViewDelegate>*/)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 /*<UIAlertViewDelegate>*/ delegate;
//保留原有代碼行間隔,比如這里原來(lái)沒(méi)有空行,那填上注釋后也沒(méi)有空行
@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.
//保留系統(tǒng)原有英文注釋;中文注釋可以在翻譯英文注釋基礎(chǔ)上豐富
//中文注釋緊鄰代碼
- (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. */
/**
 *  多參數(shù)的可以借助vvDocument插件來(lái)寫標(biāo)準(zhǔn)注釋
 *
 *  @param textFieldIndex 參數(shù)意義及使用
 *
 *  @return 返回值
 */
- (nullable UITextField *)textFieldAtIndex:(NSInteger)textFieldIndex NS_AVAILABLE_IOS(5_0);


@end

__TVOS_PROHIBITED
@protocol UIAlertViewDelegate <NSObject>
@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
最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容