On 24/09/14 05:57, Werner LEMBERG wrote: >> I believe I've matched the existing style of code layout, (which >> isn't entirely to my personal taste), but is the comment style >> acceptable? (I've annotated my changes considerably more >> comprehensively than the original). > > I don't really mind, since it isn't consistent in the groff source. > However, as far as I can see, you are adding *another* style, and I > wonder whether there is a specific reason...
None, beyond a personal preference to use C-style for *block* comments, (which are automatically formatted with an aligned column of leading asterisks, as I have vim configured), reserving... > Personally, I prefer `//' due to its uniform look. ...this for one line trailing comments, (in C++ only). But no problem: I'll change it to '//', since that seems more consistent with the style used elsewhere, in the same file. >> +static >> +/********** > > This I don't like. Please move the `static' keyword below the > comment. Okay. Should I also s?\*?/?g, on the lead-in to the function header comment block, (in addition to introducing each subsequent line with the C++ style '//')? >> + * Returns (+ve) number of input characters stored into caller's > > What is `+ve'? I've always understood it to be universally accepted -- at least in mathematical, scientific, and engineering circles -- as an abbreviation for "positive". In this context, I'm saying that for return values greater than zero, the entire input line has been read, and returned (possibly truncated); zero will indicate EOF, (with no collected input to return), while a negative return value would be available, (but not used currently), to indicate return of a partial input line, with more retrievable on a subsequent read request. Maybe the comment could be more explicit? -- Regards, Keith.
