"Andrei Alexandrescu" <seewebsiteforem...@erdani.org> wrote in message news:it3ne2$1g2f$1...@digitalmars.com... > On 6/12/11 2:19 PM, Nick Sabalausky wrote: >> "Andrei Alexandrescu"<seewebsiteforem...@erdani.org> wrote in message >> news:it32j8$2gfq$1...@digitalmars.com... >>> On 6/12/11 1:45 PM, Nick Sabalausky wrote: >>>> "Andrei Alexandrescu"<seewebsiteforem...@erdani.org> wrote in message >>>> news:it1c0f$1uup$1...@digitalmars.com... >>>>> On 06/11/2011 03:52 PM, Nick Sabalausky wrote: >>>>>> "Andrei Alexandrescu"<seewebsiteforem...@erdani.org> wrote in >>>>>> message >>>>>> news:it07ni$1pvj$1...@digitalmars.com... >>>>>>> >>>>>>> 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.