title: How should I document property setters?
body: <p>I occasionally override the setters of Objective-C properties, and was wondering. If I change the default behavior of a method drastically, where should I document this in the header? Or should I just use a new method completely?</p>
  
  <p>In my current case, I am setting a view up as a placeholder view in interface builder. Programatically, there will be a way to replace this view with a new view (Either an icon, or an arbitrary custom view). The method to swap out the placeholder view will automatically set the property to the new view, remove the placeholder view from the parent view, add the new view to the parent view, and reposition/resize the new view appropriately.</p>
  
  <p>I came up with three options:</p>
  
  <p>A) Override the setter of the property, and document along with the property:</p>
  
  <pre><code>// Documentation goes here
  // The setter of this property actually does &lt;etc&gt;
  @property (nonatomic, retain) IBOutlet UIView* placeholderView;
  </code></pre>
  
  <p>B) Override the setter, and declare it in the header:</p>
  
  <pre><code>// Documentation goes here
  -(void)setPlaceholderView:(UIView*)view;
  </code></pre>
  
  <p>C) Use a completely different method and set the property to readonly:</p>
  
  <pre><code>@property (nonatomic, retain, readonly) IBOutlet UIView* placeholderView;
  -(void)replacePlaceholderView:(UIView*)view;
  </code></pre>
  
  <p>Option C seems appealing, because it makes it quite clear what the method does. It will also be clear that since it is different than a normal setter, it may act differently (which it will). The disadvantage I see here is that it doesn't seem to follow the normal Objective-C trend.</p>
  
  <p>What do you guys think is the cleanest way to do something like this?</p>