> > Thanks, very informative! :) The only thing missing (if I haven't > > missed it) is the fact that apostrophes are used to refer to other > > parameters of the same function ... eg: > > > > ``` > > /****** ... > > * ... > > * @description: > > * Uses 'a' to meep 'b'. > > * ... > > */ > > FT_EXPORT( void ) > > FT_Meep ( A a, > > B b ); > > ``` > > Ah, this is a slight issue I'm not happy yet in the docs. I think > this should rather be > > /****** ... > * ... > * @description: > * Uses `a` to meep `b`. > * ... > */ > > In general, `@foo' should also use a typewriter face if it links to > C stuff like `@function' or `@enum'. Nikhil, any chance to adjust > `docwriter' accordingly? For 'a' vs. `a`, we probably have to walk > manually over all header files. > > This somehow slipped my attention, sorry. >
I'm not sure what cases this covers. Can you provide an example? >> * Shall we mention that we prefer two spaces after a full stop > >> ending a sentence? > > > > Please do, esp. for people who're new to FreeType; > > Yep. > > >> Ditto for details on uppercasing in section titles (US style, for > >> example `This and That'), how to cite a C function (without > >> trailing parentheses), etc., etc. > > > > Ditto, please do, for the sake of everyone who's new to contributing > > to FT :) > > Yep. > Added these! See https://github.com/nikramakrishnan/freetype-docs/wiki/Documentation-Guidelines-for-The-FreeType-Project#general-formatting-conventions >> Also, I'm not sure about the `forced' line filling to column 71 as > >> seen in other files in the `docs' directory. > > Ah, this is due to my formatting using Emacs, which has a default line > width of 72 chars. For the sake of consistency the style guide should > rather mention to use 78 chars. On the other hand, a well-formatted > document with a shorter line length doesn't hurt... > The `Comment Blocks' section already includes this. -- Nikhil
_______________________________________________ Freetype-devel mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/freetype-devel
