On Monday, July 02, 2012 21:57:54 Jacob Carlborg wrote: > It's fairly obvious that it needs to be ddoc comments, otherwise it won't > work. But there are various styles that can be used: > > * Using single line comments as multiline comments: > > /// Multiline > /// comment > > * Using multiline comments: > > /** > Multiline > comment > */ > > * Using multiline comments in Java style: > > /** > * Multiline > * comment > */ > > * Using multiline comment for single line comment > > /** Single line comment */ > > /++ > Nested comment style > +/ > > * Putting single line comments before or after the symbol
Well, honestly, I _don't_ want to require a particular style for ddoc comments. I always use /++ +/ and hate /** */ (especially when the * is at the front of every line), but there are others who prefer /** */, so we're just going to get into an argument if we try and mandate that. I say just let the programmer decide which to use. It has no effect on the generated ddoc, and most of the style guide focuses on stuff that affects the API, not how the code itself is styled. > Then when various sections that is not consistently used, like: > > * Return > * Params > * Examples > * See_Also > * Standards > * Throws > > We could have guidelines saying when these sections should and shouldn't be > used. I don't know how to picky we want to be with the documentation but > these were the things I had in mind. I don't know. I'm not sure that it's worth trying to say much on these. I don't know what we'd say. On the whole, what we've been doing has been working. I'm not against us coming up with some guidelines on these, but I don't know what they'd be, and I'd prefer to make that a separate discussion beyond sorting out my proposed changes. Guidelines like that can be added later. - Jonathan M Davis _______________________________________________ phobos mailing list [email protected] http://lists.puremagic.com/mailman/listinfo/phobos
