Flag proposal

[Jonathan M Davis]

On 2011-06-10 12:47, KennyTM~ wrote:
> On Jun 11, 11 03:40, Jonathan M Davis wrote:
> > On 2011-06-10 12:33, KennyTM~ wrote:
> >> On Jun 11, 11 03:30, Jonathan M Davis wrote:
> >>> On 2011-06-10 09:15, Andrei Alexandrescu wrote:
> >>>> https://github.com/D-Programming-Language/phobos/pull/94
> >>>> 
> >>>> Discuss!
> >>> 
> >>> I do have to admit that as much as I hate the idea of named parameters,
> >>> this particular proposal certainly seems to be an argument in favor of
> >>> adding them, which would tend to argue against making these changes.
> >>> 
> >>> After thinking about it, I'd argue that it would be better to create a
> >>> string mixin which created the enums for you instead of using the
> >>> template as part of the arguments. e.g.
> >>> 
> >>> mixin(YesNoEnum!"KeepTerminator"));
> >>> 
> >>> Then all of the rest of the code is the same. You'd still use
> >>> KeepTerminator.yes and KeepTerminator.no, but we avoided having to
> >>> create duplicate enums by hand every time that we want this kind of
> >>> variable. So, you still reduce the boilerplate code, but the usage is
> >>> much less ugly.
> >>> 
> >>> - Jonathan M Davis
> >> 
> >> The problem is the 'YesNoEnum!"KeepTerminator"' will not be shown along
> >> with the DDoc of 'getLine'.
> > 
> > Why would it be? You generally want documentation specific to the enum
> > anyway, so that isn't exactly boilerplate. You'd just stick the
> > documentation above the mixin. And if you don't want to do that but want
> > it in the documentation for the function that uses it (particularly if
> > there's only one - though that's often not the case), then just put the
> > documentation in the function's documentation. Andrei's current solution
> > does nothing for documentation, and arguably makes it worse, because
> > there's no place to put documentation on the enum directly if you need
> > to.
> > 
> > - Jonathan M Davis
> 
> Please review the previous discussion of why Flag (was YesOrNo) was
> proposed.
> 
> http://www.digitalmars.com/d/archives/digitalmars/D/YesOrNo_useful_idiom_he
> lper_or_wanking_134392.html

In many cases, I very much think that the documentation should be separate. A 
prime example would be std.datetime.AllowDayOverflow. It's use in several 
places in std.datetime, and having one place to read up on it is definitely 
beneficial. Not having a place where the enum is defined separately would 
definitely be worse in that case. The area where it's more debatable is when 
there's only _one_ function which uses the enum. Then Andrei's proposed 
solution is more reasonable. But worse comes to worst, you can _still_ put the 
documentation with the function in the current solution. Andrei's solution 
adds _nothing_ to that. It just makes it so that there isn't actually a 
separate enum somewhere which can be documented. It removes the possibility of 
documenting it.

I'd rather have the one line mixin which you can either document directly or 
skip documenting and put its documentation with the function that uses it 
rather than one where you _can't_ document it separately. std.datetime will 
_not_ switch to this even if it gets checked in simply because it will make 
the documentation worse. And I'm not sure that we want to have some enums 
using this solution and some not, since that would be inconsistent. I'm not 
entirely against Andrei's solution (it does reduce boilerplate code), but I 
think that a string mixin solution makes more sense. It's less verbose, and 
you can choose where to put its documentation.

- Jonathan M Davis