"Andrei Alexandrescu" <[email protected]> wrote in message news:[email protected]... > On 6/12/11 2:19 PM, Nick Sabalausky wrote: >> "Andrei Alexandrescu"<[email protected]> wrote in message >> news:[email protected]... >>> On 6/12/11 1:45 PM, Nick Sabalausky wrote: >>>> "Andrei Alexandrescu"<[email protected]> wrote in message >>>> news:[email protected]... >>>>> On 06/11/2011 03:52 PM, Nick Sabalausky wrote: >>>>>> "Andrei Alexandrescu"<[email protected]> wrote in >>>>>> message >>>>>> news:[email protected]... >>>>>>> >>>>>>> Anyway, that was the first thing "grep yes std/*" found. Let's see >>>>>>> the >>>>>>> next one: >>>>>>> >>>>>>> /** >>>>>>> Specifies whether the output of certain algorithm is desired in >>>>>>> sorted >>>>>>> format. >>>>>>> */ >>>>>>> enum SortOutput { >>>>>>> no, /// Don't sort output >>>>>>> yes, /// Sort output >>>>>>> } >>>>>>> >>>>>>> This already is very unpleasant because "certain" is as imprecise as >>>>>>> it >>>>>>> gets. Plus one for Flag, I hope you agree. >>>>>>> >>>>>> >>>>>> Flag -= 1 >>>>>> s/output of certain algorithm/output of an algorithm/ += 1 >>>>>> >>>>>> That one-word doc change makes it all perfectly clear. >>>>> >>>>> Not at all. The typo in the original text must have confused you: it >>>>> should be "certain algorithms" because SortOutput is used in four >>>>> distinct >>>>> algorithms (one of which has two overloads). Grep std/algorithm.d. >>>>> >>>>> Flag += 2 >>>>> >>>> >>>> Not that I consider quibbling over small English wording differences a >>>> major >>>> thing, but I fail to see how: >>>> >>>> "Specifies whether the output of an algorithm is desired in sorted >>>> format." >>>> >>>> is significantly different from: >>>> >>>> "Specifies whether the output of certain algorithms are desired in >>>> sorted >>>> format." >>>> >>>> In either case, I don't see anything problematically imprecise. >>> >>> Still means I need to jump back and forth in the documentation. >>> >> >> And you don't like the "///ditto" suggestion for handling that? > > That actually does help, but not for enums used by more than one function. > The other issues remain too. >
I would think that an enum used by more than one function *should* be listed separately.
