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

Reply via email to