My 2c, I don't care about doxygen markup anymore -- as there is no critical mass behind the idea of automatic generated docs from source here --, but I can't relate with this notion that too many comments in a header is pollution. Who would want to see just the enumeration names or the structures without annotations, and to what purpose? I really can't understand...
For a developer using or modifying the headers having the documentation right there seems the best: one can quickly lookup the documentation of a symbol by jumping to its definition in his favorite editor or IDE. It doesn't need to open another file. For me it would make sense to have a high level manual / guide in a separate document, but reference documentation is better in the source, revisioned in the same way. The best example of a well documented header that I've come across is http://cgit.freedesktop.org/mesa/mesa/tree/src/gallium/drivers/svga/include/svga3d_reg.h (written by Micah Dowty and others at VMware). It has no special markup, it omits the obvious stuff, and anybody that reads that file understands both the semantics and the syntax of the interface. My ideal for pipe/p_*.h would be something like that. All these ascii tools look nice -- I've used asciidoc many times and I'm quite happy with it --, but it is yet another markup to learn -- it appears easy but it is like every other apparently intuitive and non-intrusive markup language out there in wikis and so on, all slightly different from each other, and if if you forget a space, or use '*'' instead of '-' or some minor detail like that, you get crap in the output. You find yourself looking up the tool documentation more often that you'd expect! Anyway, having more documentation, wherever it goes, is a very good thing IMO. So whatever works is fine by be. Jose ________________________________________ From: Keith Whitwell [kei...@vmware.com] Sent: Saturday, December 19, 2009 16:42 To: tom fogal Cc: mesa3d-dev@lists.sourceforge.net Subject: Re: [Mesa3d-dev] [PATCH] gallium: add PIPE_CAP_QUADS_FOLLOW_FLATSHADE_FIRST_CONVENTION Tom, These both look great! The markup language is almost invisible and the raw documents look a lot like the sort of ascii stuff I tend to write before figuring out how to turn it into something fancier... Now just to pick one... Keith ________________________________________ From: tom fogal [tfo...@alumni.unh.edu] Sent: Saturday, December 19, 2009 8:32 AM To: Keith Whitwell Cc: Corbin Simpson; Christoph Bumiller; mesa3d-dev@lists.sourceforge.net Subject: Re: [Mesa3d-dev] [PATCH] gallium: add PIPE_CAP_QUADS_FOLLOW_FLATSHADE_FIRST_CONVENTION Keith Whitwell <kei...@vmware.com> writes: > Ideally that would mean being able to produce a single patch or patch > series that contains the changes to the headers *and* the changes to > the spec, so th at all is being considered together. That means in > turn having the spec in the git tree. Ideally we'd have an online > version as well, in a wiki style. I'm interested in suggestions for > how to make this happen. Ideally we *wouldn't* pollute the header > files with so much text and markup that they become unreadable - > ie. I don't really like the idea of doing the spec with doxygen - I'd > prefer the headers to be human-readable. Thoughts? I'm partial to / been considering both asciidoc and sphinx in my own projects. http://www.methods.co.nz/asciidoc/ http://sphinx.pocoo.org/ Both are text-based formats that are intended to be readable `raw', but are processable into more presentable formats. The git documentation: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html is done with asciidoc. Python documentation: http://docs.python.org/library/index.html is done with sphinx. -tom > ________________________________________ > From: Corbin Simpson [mostawesomed...@gmail.com] > Sent: Friday, December 18, 2009 7:11 PM > To: Christoph Bumiller > Cc: mesa3d-dev@lists.sourceforge.net > Subject: Re: [Mesa3d-dev] [PATCH] gallium: add PIPE_CAP_QUADS_FOLLOW_FLATSHA > DE_FIRST_CONVENTION > > NAK to this series. Keith hasn't responded, although I expect that he > would also NAK this. I would much rather have quads just never respect > flatshade_first as part of the spec, than jump through these weird > param hoops. > > Should somebody be documenting the API? I keep on having these kinds > of stupid edge questions come up; r300 apparently is the quirkiest > hardware of that generation. > > ~ C. > > On Fri, Dec 18, 2009 at 2:15 AM, Christoph Bumiller > <e0425...@student.tuwien.ac.at> wrote: > > Marek Olšák schrieb: > >> Hi, > >> > >> GL_ARB_provoking_vertex states that quads are not required to abide > >> the provoking vertex convention, and the actual hardware and/or driver > >> behavior can be queried with > >> GL_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION. > >> > >> I'd like to add a new PIPE_CAP_* to query for this capability in > >> Gallium, as it appears R3xx-R5xx hardware doesn't support the first > >> vertex convention for quads and I'd like the driver to behave > >> correctly. Fortunately, other primitive types are supported. > >> > >> I decided to use the name "quads follow flatshade_first convention" > >> instead of "provoking vertex convention" because the actual state > >> variable in pipe_rasterizer_state is called flatshade_first. > >> > >> The attached patch: > >> - adds PIPE_CAP_QUADS_FOLLOW_FLATSHADE_FIRST_CONVENTION > >> - adds the query in the Mesa state tracker > >> - and updates softpipe and llvmpipe to return 1 when this cap is > >> queried, and r300g to explicitly return 0 > >> > > You can add a "return 1" for nv50, too, in case you do push this patch. > > I just tested and for quads I can also make them use either the first or > > the last vertex's colour, i.e. flatshade convention is respected. > > > > Thanks, Christoph. > >> Please review/push. > >> > >> Cheers. > >> > >> Marek > >> > >> > >> ------------------------------------------------------------------------ > >> > >> -------------------------------------------------------------------------- > ---- > >> This SF.Net email is sponsored by the Verizon Developer Community > >> Take advantage of Verizon's best-in-class app development support > >> A streamlined, 14 day to market process makes app distribution fast and ea > sy > >> Join now and get one step closer to millions of Verizon customers > >> http://p.sf.net/sfu/verizon-dev2dev > >> > >> > >> ------------------------------------------------------------------------ > >> > >> _______________________________________________ > >> Mesa3d-dev mailing list > >> Mesa3d-dev@lists.sourceforge.net > >> https://lists.sourceforge.net/lists/listinfo/mesa3d-dev > > > > > > --------------------------------------------------------------------------- > --- > > This SF.Net email is sponsored by the Verizon Developer Community > > Take advantage of Verizon's best-in-class app development support > > A streamlined, 14 day to market process makes app distribution fast and eas > y > > Join now and get one step closer to millions of Verizon customers > > http://p.sf.net/sfu/verizon-dev2dev > > _______________________________________________ > > Mesa3d-dev mailing list > > Mesa3d-dev@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/mesa3d-dev > > > > > > -- > Only fools are easily impressed by what is only > barely beyond their reach. ~ Unknown > > Corbin Simpson > <mostawesomed...@gmail.com> > > ----------------------------------------------------------------------------- > - > This SF.Net email is sponsored by the Verizon Developer Community > Take advantage of Verizon's best-in-class app development support > A streamlined, 14 day to market process makes app distribution fast and easy > Join now and get one step closer to millions of Verizon customers > http://p.sf.net/sfu/verizon-dev2dev > _______________________________________________ > Mesa3d-dev mailing list > Mesa3d-dev@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/mesa3d-dev > > ----------------------------------------------------------------------------- > - > This SF.Net email is sponsored by the Verizon Developer Community > Take advantage of Verizon's best-in-class app development support > A streamlined, 14 day to market process makes app distribution fast and easy > Join now and get one step closer to millions of Verizon customers > http://p.sf.net/sfu/verizon-dev2dev > _______________________________________________ > Mesa3d-dev mailing list > Mesa3d-dev@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/mesa3d-dev ------------------------------------------------------------------------------ This SF.Net email is sponsored by the Verizon Developer Community Take advantage of Verizon's best-in-class app development support A streamlined, 14 day to market process makes app distribution fast and easy Join now and get one step closer to millions of Verizon customers http://p.sf.net/sfu/verizon-dev2dev _______________________________________________ Mesa3d-dev mailing list Mesa3d-dev@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/mesa3d-dev ------------------------------------------------------------------------------ This SF.Net email is sponsored by the Verizon Developer Community Take advantage of Verizon's best-in-class app development support A streamlined, 14 day to market process makes app distribution fast and easy Join now and get one step closer to millions of Verizon customers http://p.sf.net/sfu/verizon-dev2dev _______________________________________________ Mesa3d-dev mailing list Mesa3d-dev@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/mesa3d-dev
