HeaderDoc style for getter/setter pairs

  • I believe that instance variables accessed with getter/setter method
    pairs should be described only once in class documentation.

    However, HeaderDoc likes you to have a description with each method,
    which would be redundant for getter/setter pairs.  I'm thinking maybe
    I should list and describe the instance variables in the class
    description.  Is there a better style?

    Also, HeaderDoc would be nicer if it would group getters with their
    corresponding setters.  Does anyone know a way to make it do that?

    Jerry Krinock
  • On Dec 22, 2007, at 12:21 AM, Jerry Krinock wrote:

    > I believe that instance variables accessed with getter/setter method
    > pairs should be described only once in class documentation.
    >

    Gack

    > However, HeaderDoc likes you to have a description with each method,
    > which would be redundant for getter/setter pairs.  I'm thinking
    > maybe I should list and describe the instance variables in the class
    > description.  Is there a better style?

    Assuming you mean for public consumption? It's best to go the way we
    do now (although writing these daily that may have been pounded into me)

    getters and setters can have different usages notes that are complex
    to note if they're together.

    Having had to write more generic descriptions that apply to both get
    and set situations (for @property support in Objective-C 2.0 class
    documentation) I find that much harder to get 'right'.

    >
    >
    > Also, HeaderDoc would be nicer if it would group getters with their
    > corresponding setters.  Does anyone know a way to make it do that?

    As opposed to alphabetical order?
  • On 2007 Dec, 21, at 22:32, Scott Anguish wrote:

    > Assuming you mean for public consumption?

    Yes

    > It's best to go the way we do now (although writing these daily that
    > may have been pounded into me)
    > getters and setters can have different usages notes that are complex
    > to note if they're together.

    Fair enough, but what if, on the other hand, the getter and setter are
    dumb and simple, but the instance variable itself requires some
    @discussion.  Here's an example:

    /*!
      @method    disallowedCharacterSet
      @abstract  gets the 'disallowedCharacterSet' of the receiver
      @discussion This class defines a 'disallowedCharacterSet'.  If,
    while typing in a new
      token, the user enters a character from the disallowedCharacterSet,
    it will be replaced
      with an underscore ("_"), and the System Alert will sound.  The user
    may continue typing
      after this happens.
      @result    The 'disallowedCharacterSet' of the receiver
    */
    - (NSCharacterSet *)disallowedCharacterSet ;

    /*
      @method    setDisallowedCharacterSet:
      @abstract  sets the 'disallowedCharacterSet' of the receiver
      @discussion This class defines a 'disallowedCharacterSet'.  If,
    while typing in a new
      token, the user enters a character from the disallowedCharacterSet,
    it will be replaced
      with an underscore ("_"), and the System Alert will sound.  The user
    may continue typing
      after this happens.
      @param      The new 'disallowedCharacterSet' for the receiver
    */
    - (void)setDisallowedCharacterSet:(NSCharacterSet *)newValue;

    I hope you can appreciate why it might make more sense to me to
    describe the instance variable elsewhere, and have the getter and
    setter documentation simply reference it.

    I believe that we have to define the instance variable as some entity,
    in this case 'disallowedCharacterSet', to show the connection between
    the setter and the getter.  But since the getter and setter
    documentation are separate, I repeat the same @discussion in each.  Is
    this really the correct way to write it?  If not, please edit and show
    the way you would write it....(Scott or anyone else).

    > As opposed to alphabetical order?

    If they shared a common @discussion, it would make sense for setter to
    immediately follow getter.
  • On Dec 22, 2007, at 8:13 AM, Jerry Krinock wrote:

    >
    > On 2007 Dec, 21, at 22:32, Scott Anguish wrote:
    >
    >> It's best to go the way we do now (although writing these daily
    >> that may have been pounded into me)
    >> getters and setters can have different usages notes that are
    >> complex to note if they're together.
    >
    > Fair enough, but what if, on the other hand, the getter and setter
    > are dumb and simple, but the instance variable itself requires some
    > @discussion.  Here's an example:
    >
    > /*!
    > @method    disallowedCharacterSet
    > @abstract  gets the 'disallowedCharacterSet' of the receiver
    > @discussion This class defines a 'disallowedCharacterSet'.  If,
    > while typing in a new
    > token, the user enters a character from the
    > disallowedCharacterSet, it will be replaced
    > with an underscore ("_"), and the System Alert will sound.  The
    > user may continue typing
    > after this happens.
    > @result    The 'disallowedCharacterSet' of the receiver
    > */
    > - (NSCharacterSet *)disallowedCharacterSet ;
    >
    > /*
    > @method    setDisallowedCharacterSet:
    > @abstract  sets the 'disallowedCharacterSet' of the receiver
    > @discussion This class defines a 'disallowedCharacterSet'.  If,
    > while typing in a new
    > token, the user enters a character from the
    > disallowedCharacterSet, it will be replaced
    > with an underscore ("_"), and the System Alert will sound.  The
    > user may continue typing
    > after this happens.
    > @param      The new 'disallowedCharacterSet' for the receiver
    > */
    > - (void)setDisallowedCharacterSet:(NSCharacterSet *)newValue;
    >
    > I hope you can appreciate why it might make more sense to me to
    > describe the instance variable elsewhere, and have the getter and
    > setter documentation simply reference it.
    >
    > I believe that we have to define the instance variable as some
    > entity, in this case 'disallowedCharacterSet', to show the
    > connection between the setter and the getter.  But since the getter
    > and setter documentation are separate, I repeat the same
    > @discussion in each.  Is this really the correct way to write it?
    > If not, please edit and show the way you would write it....(Scott
    > or anyone else).
    >
    >
    >> As opposed to alphabetical order?
    >
    > If they shared a common @discussion, it would make sense for setter
    > to immediately follow getter.

    Yes it would. In fact the list should not be in alphabetical order,
    but in "cocoabetical" order. In other words, strip off the "set",
    "is", "countOf" and all other constructions that serve to scatter
    understanding of the underlying logic of the object property, sort by
    what is left, and list all the applicable methods together with a
    description of that property.

    The other useful change would be to omit almost all documentation for
    setters and getters. There is a large amount of noise present because
    of "Sets the foo object" and "Returns the foo object" kind of
    explanation. In most cases all that should be listed are the
    @properties lines lifted straight from the .h file and pasted into a
    very small section called "Setters and Getters".
  • On 2007 Dec, 22, at 8:44, Steve Weller wrote:

    > On Dec 22, 2007, at 8:13 AM, Jerry Krinock wrote:
    >
    >> If they shared a common @discussion, it would make sense for setter
    >> to immediately follow getter.
    >
    > Yes it would. In fact the list should not be in alphabetical order,
    > but in "cocoabetical" order...
    >
    > The other useful change would be to omit almost all documentation
    > for setters and getters...

    Thanks, Steve!  If this ever becomes a revolution, I will be on your
    side.

    For now, however, I need someone from the other side to show me how to
    rewrite those HeaderDoc comments in my previous post to be in
    conformance with the Currently Accepted Style.
  • Since I've received no solutions from the other side, and after
    discovering another quandary, I decided to take Steve's advice and do
    it the revolutionary way.

    The new quandary is KVC.  KVC-compliant properties can be changed
    directly, via bindings.  Therefore, explaining the ^effect^ of an
    property ^value^, in the documentation of the setter (or getter) would
    be like documenting the interior of a house in a section titled "Front
    Door".  What if someone comes in the back door or the side door?
    Don't they see the same interior?

    So, what I am doing instead is this:

    1.  The ^effect^ of each property (loosely, instance variable) is
    documented in a list of "properties" in the description for the class.

    2.  Documentation for each getter consists of a statement that it is
    "the getter for ivar foo, and an indication of any copying or
    dependencies involved in producing the return value.

    3.  Documentation for each setter consists of a statement that it is
    "the setter for ivar foo", and a discussion of any other side effects
    (other than assigning the ivar value) which occur when the setter is
    used.
previous month december 2007 next month
MTWTFSS
          1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
31            
Go to today