Как я могу документировать объекты недвижимости?

Question

Я иногда переопределяю настройки объектов Objective-C и задавался вопросом. Если я решительно поменяю поведение метода по умолчанию, где я должен документировать это в заголовке? Или я должен просто использовать новый метод полностью?

В моем текущем случае, я устанавливаю представление как вид замещателя в построителе интерфейса. Программно, будет возможность заменить это представление новым представлением (либо значком, либо произвольным пользовательским представлением). Метод поменять вид замещателя автоматически установит свойство в новое представление, удалит представление заполнителя из родительского представления, добавит новое представление в родительское представление и соответствующим образом изменит/изменит размер нового представления.

я придумал три варианта:

A) замещают сеттер свойства, а также документ наряду со свойством:

// Documentation goes here 
// The setter of this property actually does <etc> 
@property (nonatomic, retain) IBOutlet UIView* placeholderView; 

B) замещает сеттер, и объявить его в заголовке :

// Documentation goes here 
-(void)setPlaceholderView:(UIView*)view; 

с) с помощью совершенно другой метод и установить свойство ReadOnly:

@property (nonatomic, retain, readonly) IBOutlet UIView* placeholderView; 
-(void)replacePlaceholderView:(UIView*)view; 

Вариант C кажется привлекательным, поскольку он дает понять, что делает этот метод. Также будет ясно, что, поскольку он отличается от обычного сеттера, он может действовать по-другому (что будет). Недостаток, который я вижу здесь, заключается в том, что он, похоже, не соответствует обычной тенденции Objective-C.

Что вы, ребята, думаете, это самый чистый способ сделать что-то подобное?

Answer 1

Вы не должны «полностью изменять поведение по умолчанию [setter]». Метод setter должен установить свойство, и если это произойдет, вам не нужно документировать переопределение в заголовке в любом месте, поскольку оно делает именно то, что ожидал пользователь, а переопределение - это деталь реализации, которая может быть документирована в файл реализации. Радикально меняющееся ожидаемое поведение будет только сеять путаницу, и этого избежать. Идите с опцией (C), если ваше желаемое поведение не будет оправдано ожидаемым пользователем, когда она установит это свойство.

Answer 2

На практике, IBOutlet должен быть установлен только при инициализации файлов nib. Если бы я был реорганизовать это, я объявлю свойства

@property (nonatomic, weak) IBOutlet UIView *initialPlaceholderView; 
@property (nonatomic, weak) UIView *placeholderContainerView; 
@property (nonatomic, weak) UIView *currentPlaceholderView; 

затем переименовать replacePlaceholderView: в

-(void)updatePlaceholderContainerWithNewView:(UIView*)newPlaceholderView; 

Это код самодокументирован. Вы уже можете предположить поведение только по именам свойств и методов.