Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Fri, Aug 01, 2014 at 02:58:21PM +0200, Laurent Pinchart wrote: Hi Randy, On Thursday 31 July 2014 15:16:21 Randy Dunlap wrote: On 05/12/14 11:04, Randy Dunlap wrote: On 05/12/2014 08:54 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote: On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. Hm, do you have pointers to those? My google-fu seems lacking ... I googled for /kernel doc asciidoc ravnborg/ and found several hits for them. Ok, let's move this to the top and start discussions. The past few months I've written piles of kerneldoc comments for the DRM DocBook (all pulled in as kerneldoc, docbook .tmpl has just the chapter structure). DOC: sections are really useful to pull all the actual documentation out of the docbook xml into kerneldoc. But I've also done piles of docs for intel-gpu-tools, which is using gtkdoc. And there are some clear deficiencies: - No markdown for inline coments. Lack of lists and tables is hurting especially badly. If we add this (and I don't care one iota whether it's Yes, I've tried to add lists to kernel-doc notation but have failed so far. markdown or asciidoc or something else as long as it's readable plain text in comments) we should be able to move all the existing docbook xml paragraphs/lists/tables into kerneldoc comments. - Automatic cross-referencing of functions. If you place e.g. function() or #struct anywhere in a documentation comment gtk-doc automatically inserts a hyperlink to the relevant documentation page across the entire project. Really powerful and makes overview sections much more useful entry points for beginners since they can easily jump backforth betweeen the high-level overview and low-level per-function documentation. That's a nice-to-have IMO, but a really nice one. - In a really perfect world it would help if kerneldoc could collect structure member kerneldoc from per-member comments. Especially for large structures with lots of comments this would bring the kerneldoc and struct member much closer together. So that's my wishlist. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. Hm, I don't mind docbook at all, as long as all the real content is embedded into source files as kerneldoc and the docbook template just pulls in all the right bits and pieces. Even gtkdoc allos you to do that and pull in the different libararies (== header files with declarations for C) in the order you
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Monday 04 August 2014 09:30:04 Daniel Vetter wrote: On Fri, Aug 01, 2014 at 02:58:21PM +0200, Laurent Pinchart wrote: On Thursday 31 July 2014 15:16:21 Randy Dunlap wrote: On 05/12/14 11:04, Randy Dunlap wrote: On 05/12/2014 08:54 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote: On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. Hm, do you have pointers to those? My google-fu seems lacking ... I googled for /kernel doc asciidoc ravnborg/ and found several hits for them. Ok, let's move this to the top and start discussions. The past few months I've written piles of kerneldoc comments for the DRM DocBook (all pulled in as kerneldoc, docbook .tmpl has just the chapter structure). DOC: sections are really useful to pull all the actual documentation out of the docbook xml into kerneldoc. But I've also done piles of docs for intel-gpu-tools, which is using gtkdoc. And there are some clear deficiencies: - No markdown for inline coments. Lack of lists and tables is hurting especially badly. If we add this (and I don't care one iota whether it's Yes, I've tried to add lists to kernel-doc notation but have failed so far. markdown or asciidoc or something else as long as it's readable plain text in comments) we should be able to move all the existing docbook xml paragraphs/lists/tables into kerneldoc comments. - Automatic cross-referencing of functions. If you place e.g. function() or #struct anywhere in a documentation comment gtk-doc automatically inserts a hyperlink to the relevant documentation page across the entire project. Really powerful and makes overview sections much more useful entry points for beginners since they can easily jump backforth betweeen the high-level overview and low- level per-function documentation. That's a nice-to-have IMO, but a really nice one. - In a really perfect world it would help if kerneldoc could collect structure member kerneldoc from per-member comments. Especially for large structures with lots of comments this would bring the kerneldoc and struct member much closer together. So that's my wishlist. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. Hm, I don't mind docbook at all, as long as all the real content is embedded into source files as kerneldoc and the docbook template just pulls in all the right bits and pieces. Even gtkdoc allos you to do that and pull in the different libararies (== header files with declarations for C) in the order you want. So imo the docbook toolchain is good enough
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
Hi Randy, On Thursday 31 July 2014 15:16:21 Randy Dunlap wrote: On 05/12/14 11:04, Randy Dunlap wrote: On 05/12/2014 08:54 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote: On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. Hm, do you have pointers to those? My google-fu seems lacking ... I googled for /kernel doc asciidoc ravnborg/ and found several hits for them. Ok, let's move this to the top and start discussions. The past few months I've written piles of kerneldoc comments for the DRM DocBook (all pulled in as kerneldoc, docbook .tmpl has just the chapter structure). DOC: sections are really useful to pull all the actual documentation out of the docbook xml into kerneldoc. But I've also done piles of docs for intel-gpu-tools, which is using gtkdoc. And there are some clear deficiencies: - No markdown for inline coments. Lack of lists and tables is hurting especially badly. If we add this (and I don't care one iota whether it's Yes, I've tried to add lists to kernel-doc notation but have failed so far. markdown or asciidoc or something else as long as it's readable plain text in comments) we should be able to move all the existing docbook xml paragraphs/lists/tables into kerneldoc comments. - Automatic cross-referencing of functions. If you place e.g. function() or #struct anywhere in a documentation comment gtk-doc automatically inserts a hyperlink to the relevant documentation page across the entire project. Really powerful and makes overview sections much more useful entry points for beginners since they can easily jump backforth betweeen the high-level overview and low-level per-function documentation. That's a nice-to-have IMO, but a really nice one. - In a really perfect world it would help if kerneldoc could collect structure member kerneldoc from per-member comments. Especially for large structures with lots of comments this would bring the kerneldoc and struct member much closer together. So that's my wishlist. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. Hm, I don't mind docbook at all, as long as all the real content is embedded into source files as kerneldoc and the docbook template just pulls in all the right bits and pieces. Even gtkdoc allos you to do that and pull in the different libararies (== header files with declarations for C) in the order you want. So imo the docbook toolchain is good enough for my needs. Or what do you mean by getting rid of all docbook usage? I meant no docbook style sheets, no
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On 08/01/14 05:58, Laurent Pinchart wrote: Hi Randy, On Thursday 31 July 2014 15:16:21 Randy Dunlap wrote: On 05/12/14 11:04, Randy Dunlap wrote: On 05/12/2014 08:54 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote: On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. Hm, do you have pointers to those? My google-fu seems lacking ... I googled for /kernel doc asciidoc ravnborg/ and found several hits for them. Ok, let's move this to the top and start discussions. The past few months I've written piles of kerneldoc comments for the DRM DocBook (all pulled in as kerneldoc, docbook .tmpl has just the chapter structure). DOC: sections are really useful to pull all the actual documentation out of the docbook xml into kerneldoc. But I've also done piles of docs for intel-gpu-tools, which is using gtkdoc. And there are some clear deficiencies: - No markdown for inline coments. Lack of lists and tables is hurting especially badly. If we add this (and I don't care one iota whether it's Yes, I've tried to add lists to kernel-doc notation but have failed so far. markdown or asciidoc or something else as long as it's readable plain text in comments) we should be able to move all the existing docbook xml paragraphs/lists/tables into kerneldoc comments. - Automatic cross-referencing of functions. If you place e.g. function() or #struct anywhere in a documentation comment gtk-doc automatically inserts a hyperlink to the relevant documentation page across the entire project. Really powerful and makes overview sections much more useful entry points for beginners since they can easily jump backforth betweeen the high-level overview and low-level per-function documentation. That's a nice-to-have IMO, but a really nice one. - In a really perfect world it would help if kerneldoc could collect structure member kerneldoc from per-member comments. Especially for large structures with lots of comments this would bring the kerneldoc and struct member much closer together. So that's my wishlist. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. Hm, I don't mind docbook at all, as long as all the real content is embedded into source files as kerneldoc and the docbook template just pulls in all the right bits and pieces. Even gtkdoc allos you to do that and pull in the different libararies (== header files with declarations for C) in the order you want. So imo the docbook toolchain is good enough for my needs. Or what do you mean by getting rid of all docbook usage? I meant no docbook style sheets, no 'xmlto', the whole ball of wax. But primarily I don't want to see drivers/video/ using
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On 05/12/14 11:04, Randy Dunlap wrote: On 05/12/2014 08:54 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote: On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) -Daniel I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. Hm, do you have pointers to those? My google-fu seems lacking ... I googled for /kernel doc asciidoc ravnborg/ and found several hits for them. Ok, let's move this to the top and start discussions. The past few months I've written piles of kerneldoc comments for the DRM DocBook (all pulled in as kerneldoc, docbook .tmpl has just the chapter structure). DOC: sections are really useful to pull all the actual documentation out of the docbook xml into kerneldoc. But I've also done piles of docs for intel-gpu-tools, which is using gtkdoc. And there are some clear deficiencies: - No markdown for inline coments. Lack of lists and tables is hurting especially badly. If we add this (and I don't care one iota whether it's Yes, I've tried to add lists to kernel-doc notation but have failed so far. markdown or asciidoc or something else as long as it's readable plain text in comments) we should be able to move all the existing docbook xml paragraphs/lists/tables into kerneldoc comments. - Automatic cross-referencing of functions. If you place e.g. function() or #struct anywhere in a documentation comment gtk-doc automatically inserts a hyperlink to the relevant documentation page across the entire project. Really powerful and makes overview sections much more useful entry points for beginners since they can easily jump backforth betweeen the high-level overview and low-level per-function documentation. That's a nice-to-have IMO, but a really nice one. - In a really perfect world it would help if kerneldoc could collect structure member kerneldoc from per-member comments. Especially for large structures with lots of comments this would bring the kerneldoc and struct member much closer together. So that's my wishlist. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. Hm, I don't mind docbook at all, as long as all the real content is embedded into source files as kerneldoc and the docbook template just pulls in all the right bits and pieces. Even gtkdoc allos you to do that and pull in the different libararies (== header files with declarations for C) in the order you want. So imo the docbook toolchain is good enough for my needs. Or what do you mean by getting rid of all docbook usage? I meant no docbook style sheets, no 'xmlto', the whole ball of wax. But primarily I don't want to see drivers/video/ using one set of doc tools and drivers/media/ using another set and drivers/xyz/ using its own
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Mon, May 12, 2014 at 10:03:55AM +0200, Daniel Vetter wrote: On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: I support approach using docbook to start since there are not lot of properties. Laurent has ack'ed this one. Can we go ahead with this? http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html Adding description of new property is not very complex (assuming table format is understood and being comfortable with HTML row/table manipulation). Adding description of each property in their source might be time consuming task. Yeah I'm ok with docbook for the time being. My long-term plan is to fix up kerneldoc to support markdown and then we can move such neat tables into the code. There's lots other places that would benefit from proper list formatting and tables. So Ack from my side on both the docbook patch and the no-more-props-without-doc-patch rule (which is kinda what I've been doing thus far). What happened to the proposal to add this to the Documentation/ABI directory? That already contains a bunch of files describing userspace ABI (although most of it is sysfs-related). The objection that I have to including property documentation in docbook is that the DRM docbook is documentation targetted at driver developers, but properties are userspace ABI. Therefore I think we should be using mechanisms that have been used to document other userspace ABI before to make it easier for people to find (and for consistency). One big advantage in using Documentation/ABI is that there's a fairly well documented process of how to add, deprecate and remove ABI. There's also a template that should be followed when writing these files. People have obviously put some thought into this before, so it would be a bit of a waste trying to come up with our own. The README file has some good information about all of this and I think it matches what we need fairly well. In particular I like the concept of the Users section, which could save us a lot of work trying to track potential users of crufty ABI retrospectively. Thierry pgpxqEQ5_zEyO.pgp Description: PGP signature ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Tue, May 13, 2014 at 9:17 AM, Thierry Reding thierry.red...@gmail.com wrote: On Mon, May 12, 2014 at 10:03:55AM +0200, Daniel Vetter wrote: On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: I support approach using docbook to start since there are not lot of properties. Laurent has ack'ed this one. Can we go ahead with this? http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html Adding description of new property is not very complex (assuming table format is understood and being comfortable with HTML row/table manipulation). Adding description of each property in their source might be time consuming task. Yeah I'm ok with docbook for the time being. My long-term plan is to fix up kerneldoc to support markdown and then we can move such neat tables into the code. There's lots other places that would benefit from proper list formatting and tables. So Ack from my side on both the docbook patch and the no-more-props-without-doc-patch rule (which is kinda what I've been doing thus far). What happened to the proposal to add this to the Documentation/ABI directory? That already contains a bunch of files describing userspace ABI (although most of it is sysfs-related). The objection that I have to including property documentation in docbook is that the DRM docbook is documentation targetted at driver developers, but properties are userspace ABI. Therefore I think we should be using mechanisms that have been used to document other userspace ABI before to make it easier for people to find (and for consistency). One big advantage in using Documentation/ABI is that there's a fairly well documented process of how to add, deprecate and remove ABI. There's also a template that should be followed when writing these files. People have obviously put some thought into this before, so it would be a bit of a waste trying to come up with our own. The README file has some good information about all of this and I think it matches what we need fairly well. In particular I like the concept of the Users section, which could save us a lot of work trying to track potential users of crufty ABI retrospectively. Not really sold on this, since in the end if we break userspace we have to fix it up anyway. And all these properties are meant to be used by userspace after all. I think for properties it's more important to keep them all grouped together so that if new driver writes look for something to use they don't reinvent a slight variation of something existing again. Documentation/ABI otoh seems to split things up per-knob, even across stable/testing/deprecated directories. Also eventually I want to pull these tables directly out of source code comments - everything else tends to never get updated when the code changes. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Tue, May 13, 2014 at 09:34:45AM +0200, Daniel Vetter wrote: On Tue, May 13, 2014 at 9:17 AM, Thierry Reding thierry.red...@gmail.com wrote: On Mon, May 12, 2014 at 10:03:55AM +0200, Daniel Vetter wrote: On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: I support approach using docbook to start since there are not lot of properties. Laurent has ack'ed this one. Can we go ahead with this? http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html Adding description of new property is not very complex (assuming table format is understood and being comfortable with HTML row/table manipulation). Adding description of each property in their source might be time consuming task. Yeah I'm ok with docbook for the time being. My long-term plan is to fix up kerneldoc to support markdown and then we can move such neat tables into the code. There's lots other places that would benefit from proper list formatting and tables. So Ack from my side on both the docbook patch and the no-more-props-without-doc-patch rule (which is kinda what I've been doing thus far). What happened to the proposal to add this to the Documentation/ABI directory? That already contains a bunch of files describing userspace ABI (although most of it is sysfs-related). The objection that I have to including property documentation in docbook is that the DRM docbook is documentation targetted at driver developers, but properties are userspace ABI. Therefore I think we should be using mechanisms that have been used to document other userspace ABI before to make it easier for people to find (and for consistency). One big advantage in using Documentation/ABI is that there's a fairly well documented process of how to add, deprecate and remove ABI. There's also a template that should be followed when writing these files. People have obviously put some thought into this before, so it would be a bit of a waste trying to come up with our own. The README file has some good information about all of this and I think it matches what we need fairly well. In particular I like the concept of the Users section, which could save us a lot of work trying to track potential users of crufty ABI retrospectively. Not really sold on this, since in the end if we break userspace we have to fix it up anyway. And all these properties are meant to be used by userspace after all. It's precisely because they are used by userspace that I think it's a good idea to have them documented in a place where userspace developers would look for them. I don't think anyone will look at the DRM docbook because it's targetted at driver developers. That said there is a tiny section called Userland interfaces, so perhaps adding code to that and pointing everyone at it would be an option. In which case I still think we should follow some of the same guidelines as outlined in the ABI documentation about deprecating and versioning properties. Keeping a list of known users would also be great to have in case we ever need to modify or want to remove ABI. I think for properties it's more important to keep them all grouped together so that if new driver writes look for something to use they don't reinvent a slight variation of something existing again. Documentation/ABI otoh seems to split things up per-knob, even across stable/testing/deprecated directories. I guess that's mostly a matter of convention. We could easily add a drm subdirectory that contains the DRM property documentation. And in my opinion having to scan a list of file names, such as: drm-connector-property-foo drm-plane-property-bar drm-plane-property-baz isn't any more difficult than scanning the same list in docbook format. So either way people will have to know where to look and then bother to look in order for this to work. Whether it's in Documentation/ABI or docbook is irrelevant. Also there's a good reason for having the stable/testing/deprecated split. That could also give additional hints as to whether it's a good idea to add some property or not. If somebody were to add a property to their driver that's been deprecated or removed for some other driver, a look at the corresponding file should indicate why it was removed. That could be valuable in pointing people in the right direction. Similarly, if some property was documented in the stable subdirectory, that would indicate that it's been deemed ready for prime time and give more credibility. It also means that more userspace is likely to use it and therefore might be higher priority to implement in new drivers. Also eventually I want to pull these tables directly out of source code comments - everything else tends to never get updated when the code changes. There are no guarantees that people will keep code comments up-to-date either. The only way you can make sure of that is by reviewing patches carefully.
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
Hi Daniel, On Tuesday 13 May 2014 09:34:45 Daniel Vetter wrote: On Tue, May 13, 2014 at 9:17 AM, Thierry Reding wrote: On Mon, May 12, 2014 at 10:03:55AM +0200, Daniel Vetter wrote: On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: I support approach using docbook to start since there are not lot of properties. Laurent has ack'ed this one. Can we go ahead with this? http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html Adding description of new property is not very complex (assuming table format is understood and being comfortable with HTML row/table manipulation). Adding description of each property in their source might be time consuming task. Yeah I'm ok with docbook for the time being. My long-term plan is to fix up kerneldoc to support markdown and then we can move such neat tables into the code. There's lots other places that would benefit from proper list formatting and tables. So Ack from my side on both the docbook patch and the no-more-props-without-doc-patch rule (which is kinda what I've been doing thus far). What happened to the proposal to add this to the Documentation/ABI directory? That already contains a bunch of files describing userspace ABI (although most of it is sysfs-related). The objection that I have to including property documentation in docbook is that the DRM docbook is documentation targetted at driver developers, but properties are userspace ABI. Therefore I think we should be using mechanisms that have been used to document other userspace ABI before to make it easier for people to find (and for consistency). One big advantage in using Documentation/ABI is that there's a fairly well documented process of how to add, deprecate and remove ABI. There's also a template that should be followed when writing these files. People have obviously put some thought into this before, so it would be a bit of a waste trying to come up with our own. The README file has some good information about all of this and I think it matches what we need fairly well. In particular I like the concept of the Users section, which could save us a lot of work trying to track potential users of crufty ABI retrospectively. Not really sold on this, since in the end if we break userspace we have to fix it up anyway. And all these properties are meant to be used by userspace after all. I think for properties it's more important to keep them all grouped together so that if new driver writes look for something to use they don't reinvent a slight variation of something existing again. Documentation/ABI otoh seems to split things up per-knob, even across stable/testing/deprecated directories. Also eventually I want to pull these tables directly out of source code comments - everything else tends to never get updated when the code changes. On the subject of moving documentation from docbook to source code, do your kerneldoc extensions plans include supporting images ? A drawing is worth a thousand words (see http://linuxtv.org/downloads/v4l-dvb-apis/subdev.html#subdev-image-processing-scaling-multi-source for instance), and that's currently a pretty important feature of the docbook format. -- Regards, Laurent Pinchart ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Tue, May 13, 2014 at 1:02 PM, Laurent Pinchart laurent.pinch...@ideasonboard.com wrote: Also eventually I want to pull these tables directly out of source code comments - everything else tends to never get updated when the code changes. On the subject of moving documentation from docbook to source code, do your kerneldoc extensions plans include supporting images ? A drawing is worth a thousand words (see http://linuxtv.org/downloads/v4l-dvb-apis/subdev.html#subdev-image-processing-scaling-multi-source for instance), and that's currently a pretty important feature of the docbook format. That looks great I think I'll get a bit of doc envy ;-) I don't think there's any reasonable way to generate such figures from comments, maybe for simple ones some ascii art might work out. But converting that to svg for the docbook seems to be an unsovled problem (I've only found some hacks), so I think we need to manually pull those into the docbook still. But excellent point for consideration. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
I support approach using docbook to start since there are not lot of properties. Laurent has ack'ed this one. Can we go ahead with this? http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html Adding description of new property is not very complex (assuming table format is understood and being comfortable with HTML row/table manipulation). Adding description of each property in their source might be time consuming task. thanks, Sagar On Sat, 2014-05-10 at 06:56 -0400, Rob Clark wrote: On Sat, May 10, 2014 at 6:39 AM, Ville Syrjälä ville.syrj...@linux.intel.com wrote: On Wed, Mar 12, 2014 at 12:25:06PM +0100, Laurent Pinchart wrote: Hi Sagar, On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote: On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: On Wed, Mar 5, 2014 at 11:56 AM, sagar.a.kam...@intel.com wrote: +table border=1 cellpadding=0 cellspacing=0 +tbody +tr style=font-weight: bold; +td valign=top Owner Module/Drivers/td +td valign=top Group/td +td valign=top Property Object/td +td valign=top Property Name/td +td valign=top Type/td +td valign=top Property Values/td +td valign=top Object attached/td +td valign=top Description/td +/tr In my opinion this is a horrible way to write property documentations - explicitly constructing html tables is error prone and really hard to read in the source. Imo docbook in general is rather horrible, which is way I write almost all my docs as kerneldoc ;-) I think a simple asciidoc/markdown would be much simpler, with a bit of free-form structure to group properties into relevant groups. Long-term we might even need to split it up into different spec files to keep a good overview. Docbook is indeed hard to read and write when it comes to such tables. However I like having the properties documented in the DRM core documentation. Maybe we could come up with a simpler text format that would be transformed into docbook when compiling the documentation ? Does this mean we need to create comment block with Doc: drm properties style section in each driver where drm properties are instantiated. And then in drm.tmpl collect all these using !P escape sequence? How do create table out of these across all drivers? I don't have a strong preference here. Documenting properties in source code comments would be fine, so would an external central documentation file in a non Docbook format. For the record I'm personally fine with using Docbook as in this patch :-) If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Either way I can tell you that I'm not very enthusiastic about reviewing any property patches until some kind of decision about this is reached, be it docbook, text, plan c, or fuck it, let the world burn!. any of the first three options would be vastly superior to what we do now tbh, I'd suggest imposing a no-new-properties-without-docs rule even if we haven't finished bikeshedding about the docs format. That might motivate someone to hurry up and just pick one. We can change the format, figure out some way to get it into docbook, etc, later.. it's not such a huge volume of words we have to type here that we can't reformat it later. BR, -R -- Ville Syrjälä Intel OTC ___ dri-devel mailing list dri-de...@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/dri-devel ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: I support approach using docbook to start since there are not lot of properties. Laurent has ack'ed this one. Can we go ahead with this? http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html Adding description of new property is not very complex (assuming table format is understood and being comfortable with HTML row/table manipulation). Adding description of each property in their source might be time consuming task. Yeah I'm ok with docbook for the time being. My long-term plan is to fix up kerneldoc to support markdown and then we can move such neat tables into the code. There's lots other places that would benefit from proper list formatting and tables. So Ack from my side on both the docbook patch and the no-more-props-without-doc-patch rule (which is kinda what I've been doing thus far). -Daniel thanks, Sagar On Sat, 2014-05-10 at 06:56 -0400, Rob Clark wrote: On Sat, May 10, 2014 at 6:39 AM, Ville Syrjälä ville.syrj...@linux.intel.com wrote: On Wed, Mar 12, 2014 at 12:25:06PM +0100, Laurent Pinchart wrote: Hi Sagar, On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote: On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: On Wed, Mar 5, 2014 at 11:56 AM, sagar.a.kam...@intel.com wrote: +table border=1 cellpadding=0 cellspacing=0 +tbody +tr style=font-weight: bold; +td valign=top Owner Module/Drivers/td +td valign=top Group/td +td valign=top Property Object/td +td valign=top Property Name/td +td valign=top Type/td +td valign=top Property Values/td +td valign=top Object attached/td +td valign=top Description/td +/tr In my opinion this is a horrible way to write property documentations - explicitly constructing html tables is error prone and really hard to read in the source. Imo docbook in general is rather horrible, which is way I write almost all my docs as kerneldoc ;-) I think a simple asciidoc/markdown would be much simpler, with a bit of free-form structure to group properties into relevant groups. Long-term we might even need to split it up into different spec files to keep a good overview. Docbook is indeed hard to read and write when it comes to such tables. However I like having the properties documented in the DRM core documentation. Maybe we could come up with a simpler text format that would be transformed into docbook when compiling the documentation ? Does this mean we need to create comment block with Doc: drm properties style section in each driver where drm properties are instantiated. And then in drm.tmpl collect all these using !P escape sequence? How do create table out of these across all drivers? I don't have a strong preference here. Documenting properties in source code comments would be fine, so would an external central documentation file in a non Docbook format. For the record I'm personally fine with using Docbook as in this patch :-) If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Either way I can tell you that I'm not very enthusiastic about reviewing any property patches until some kind of decision about this is reached, be it docbook, text, plan c, or fuck it, let the world burn!. any of the first three options would be vastly superior to what we do now tbh, I'd suggest imposing a no-new-properties-without-docs rule even if we haven't finished bikeshedding about the docs format. That might motivate someone to hurry up and just pick one. We can change the format, figure out some way to get it into docbook, etc, later.. it's
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Dave. ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) -Daniel I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. thanks, -- ~Randy ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote: On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) -Daniel I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. Hm, do you have pointers to those? My google-fu seems lacking ... Ok, let's move this to the top and start discussions. The past few months I've written piles of kerneldoc comments for the DRM DocBook (all pulled in as kerneldoc, docbook .tmpl has just the chapter structure). DOC: sections are really useful to pull all the actual documentation out of the docbook xml into kerneldoc. But I've also done piles of docs for intel-gpu-tools, which is using gtkdoc. And there are some clear deficiencies: - No markdown for inline coments. Lack of lists and tables is hurting especially badly. If we add this (and I don't care one iota whether it's markdown or asciidoc or something else as long as it's readable plain text in comments) we should be able to move all the existing docbook xml paragraphs/lists/tables into kerneldoc comments. - Automatic cross-referencing of functions. If you place e.g. function() or #struct anywhere in a documentation comment gtk-doc automatically inserts a hyperlink to the relevant documentation page across the entire project. Really powerful and makes overview sections much more useful entry points for beginners since they can easily jump backforth betweeen the high-level overview and low-level per-function documentation. - In a really perfect world it would help if kerneldoc could collect structure member kerneldoc from per-member comments. Especially for large structures with lots of comments this would bring the kerneldoc and struct member much closer together. So that's my wishlist. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. Hm, I don't mind docbook at all, as long as all the real content is embedded into source files as kerneldoc and the docbook template just pulls in all the right bits and pieces. Even gtkdoc allos you to do that and pull in the different libararies (== header files with declarations for C) in the order you want. So imo the docbook toolchain is good enough for my needs. Or what do you mean by getting rid of all docbook usage? -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On 05/12/2014 08:54 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote: On 05/12/2014 01:58 AM, Daniel Vetter wrote: On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote: If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Yeah I'm happy to block merging stuff, if we can spot new properties when stuff is posted on dri-devel, so much the better, most drivers still send everything via dri-devel anyways, its only really Intel I have to worry about so far, I'll enforce that all prop stuff gets cc: dri-devel and that it has updates for the prop docs. But we should definitely add it to the new driver review checklist as well. I'm also on the side of this patch is ugly and makes my eyes burn, please please get a plan to use something else ASAP, I'm willing to merge this but I'm tempted to give it a lifetime of a kernel or two before I burn it. Ok, I'll try to move make kerneldoc suck less up the task list and maybe find someone to do it for me internally ;-) -Daniel I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. Hm, do you have pointers to those? My google-fu seems lacking ... I googled for /kernel doc asciidoc ravnborg/ and found several hits for them. Ok, let's move this to the top and start discussions. The past few months I've written piles of kerneldoc comments for the DRM DocBook (all pulled in as kerneldoc, docbook .tmpl has just the chapter structure). DOC: sections are really useful to pull all the actual documentation out of the docbook xml into kerneldoc. But I've also done piles of docs for intel-gpu-tools, which is using gtkdoc. And there are some clear deficiencies: - No markdown for inline coments. Lack of lists and tables is hurting especially badly. If we add this (and I don't care one iota whether it's Yes, I've tried to add lists to kernel-doc notation but have failed so far. markdown or asciidoc or something else as long as it's readable plain text in comments) we should be able to move all the existing docbook xml paragraphs/lists/tables into kerneldoc comments. - Automatic cross-referencing of functions. If you place e.g. function() or #struct anywhere in a documentation comment gtk-doc automatically inserts a hyperlink to the relevant documentation page across the entire project. Really powerful and makes overview sections much more useful entry points for beginners since they can easily jump backforth betweeen the high-level overview and low-level per-function documentation. That's a nice-to-have IMO, but a really nice one. - In a really perfect world it would help if kerneldoc could collect structure member kerneldoc from per-member comments. Especially for large structures with lots of comments this would bring the kerneldoc and struct member much closer together. So that's my wishlist. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. Hm, I don't mind docbook at all, as long as all the real content is embedded into source files as kerneldoc and the docbook template just pulls in all the right bits and pieces. Even gtkdoc allos you to do that and pull in the different libararies (== header files with declarations for C) in the order you want. So imo the docbook toolchain is good enough for my needs. Or what do you mean by getting rid of all docbook usage? I meant no docbook style sheets, no 'xmlto', the whole ball of wax. But primarily I don't want to see drivers/video/ using one set of doc tools and drivers/media/ using another set and drivers/xyz/ using its own set of tools, etc. etc. etc. -- ~Randy
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Wed, Mar 12, 2014 at 12:25:06PM +0100, Laurent Pinchart wrote: Hi Sagar, On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote: On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: On Wed, Mar 5, 2014 at 11:56 AM, sagar.a.kam...@intel.com wrote: +table border=1 cellpadding=0 cellspacing=0 +tbody +tr style=font-weight: bold; +td valign=top Owner Module/Drivers/td +td valign=top Group/td +td valign=top Property Object/td +td valign=top Property Name/td +td valign=top Type/td +td valign=top Property Values/td +td valign=top Object attached/td +td valign=top Description/td +/tr In my opinion this is a horrible way to write property documentations - explicitly constructing html tables is error prone and really hard to read in the source. Imo docbook in general is rather horrible, which is way I write almost all my docs as kerneldoc ;-) I think a simple asciidoc/markdown would be much simpler, with a bit of free-form structure to group properties into relevant groups. Long-term we might even need to split it up into different spec files to keep a good overview. Docbook is indeed hard to read and write when it comes to such tables. However I like having the properties documented in the DRM core documentation. Maybe we could come up with a simpler text format that would be transformed into docbook when compiling the documentation ? Does this mean we need to create comment block with Doc: drm properties style section in each driver where drm properties are instantiated. And then in drm.tmpl collect all these using !P escape sequence? How do create table out of these across all drivers? I don't have a strong preference here. Documenting properties in source code comments would be fine, so would an external central documentation file in a non Docbook format. For the record I'm personally fine with using Docbook as in this patch :-) If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Either way I can tell you that I'm not very enthusiastic about reviewing any property patches until some kind of decision about this is reached, be it docbook, text, plan c, or fuck it, let the world burn!. -- Ville Syrjälä Intel OTC ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
On Sat, May 10, 2014 at 6:39 AM, Ville Syrjälä ville.syrj...@linux.intel.com wrote: On Wed, Mar 12, 2014 at 12:25:06PM +0100, Laurent Pinchart wrote: Hi Sagar, On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote: On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: On Wed, Mar 5, 2014 at 11:56 AM, sagar.a.kam...@intel.com wrote: +table border=1 cellpadding=0 cellspacing=0 +tbody +tr style=font-weight: bold; +td valign=top Owner Module/Drivers/td +td valign=top Group/td +td valign=top Property Object/td +td valign=top Property Name/td +td valign=top Type/td +td valign=top Property Values/td +td valign=top Object attached/td +td valign=top Description/td +/tr In my opinion this is a horrible way to write property documentations - explicitly constructing html tables is error prone and really hard to read in the source. Imo docbook in general is rather horrible, which is way I write almost all my docs as kerneldoc ;-) I think a simple asciidoc/markdown would be much simpler, with a bit of free-form structure to group properties into relevant groups. Long-term we might even need to split it up into different spec files to keep a good overview. Docbook is indeed hard to read and write when it comes to such tables. However I like having the properties documented in the DRM core documentation. Maybe we could come up with a simpler text format that would be transformed into docbook when compiling the documentation ? Does this mean we need to create comment block with Doc: drm properties style section in each driver where drm properties are instantiated. And then in drm.tmpl collect all these using !P escape sequence? How do create table out of these across all drivers? I don't have a strong preference here. Documenting properties in source code comments would be fine, so would an external central documentation file in a non Docbook format. For the record I'm personally fine with using Docbook as in this patch :-) If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. Can comeone pick up the ball here and figure out what needs to be done? The reason why I want a central place for the documentation is to force people to collaborate outside their own sandbox when adding properties. Whether that's docbook or some text file I don't care so much at this point. The fact that it's a central place should mandate that the patches changing it will go through dri-devel and so everyone should se them, and when adding new properties it would make the patch author more likely to look around a bit before adding another slighty incompatible version of the same property. If someone has a better suggestion how to encforce this I'm all ears. Of course this idea can still fail if our esteemed maintainer merges stuff without checking for violations of this policy. Dave, any thoughts on the subject? Either way I can tell you that I'm not very enthusiastic about reviewing any property patches until some kind of decision about this is reached, be it docbook, text, plan c, or fuck it, let the world burn!. any of the first three options would be vastly superior to what we do now tbh, I'd suggest imposing a no-new-properties-without-docs rule even if we haven't finished bikeshedding about the docs format. That might motivate someone to hurry up and just pick one. We can change the format, figure out some way to get it into docbook, etc, later.. it's not such a huge volume of words we have to type here that we can't reformat it later. BR, -R -- Ville Syrjälä Intel OTC ___ dri-devel mailing list dri-de...@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/dri-devel ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
Hi Laurent, Daniel On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: Hi Daniel, On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: On Wed, Mar 5, 2014 at 11:56 AM, sagar.a.kam...@intel.com wrote: +table border=1 cellpadding=0 cellspacing=0 +tbody +tr style=font-weight: bold; +td valign=top Owner Module/Drivers/td +td valign=top Group/td +td valign=top Property Object/td +td valign=top Property Name/td +td valign=top Type/td +td valign=top Property Values/td +td valign=top Object attached/td +td valign=top Description/td +/tr In my opinion this is a horrible way to write property documentations - explicitly constructing html tables is error prone and really hard to read in the source. Imo docbook in general is rather horrible, which is way I write almost all my docs as kerneldoc ;-) I think a simple asciidoc/markdown would be much simpler, with a bit of free-form structure to group properties into relevant groups. Long-term we might even need to split it up into different spec files to keep a good overview. Docbook is indeed hard to read and write when it comes to such tables. However I like having the properties documented in the DRM core documentation. Maybe we could come up with a simpler text format that would be transformed into docbook when compiling the documentation ? Does this mean we need to create comment block with Doc: drm properties style section in each driver where drm properties are instantiated. And then in drm.tmpl collect all these using !P escape sequence? How do create table out of these across all drivers? ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers
Hi Sagar, On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote: On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: On Wed, Mar 5, 2014 at 11:56 AM, sagar.a.kam...@intel.com wrote: +table border=1 cellpadding=0 cellspacing=0 +tbody +tr style=font-weight: bold; +td valign=top Owner Module/Drivers/td +td valign=top Group/td +td valign=top Property Object/td +td valign=top Property Name/td +td valign=top Type/td +td valign=top Property Values/td +td valign=top Object attached/td +td valign=top Description/td +/tr In my opinion this is a horrible way to write property documentations - explicitly constructing html tables is error prone and really hard to read in the source. Imo docbook in general is rather horrible, which is way I write almost all my docs as kerneldoc ;-) I think a simple asciidoc/markdown would be much simpler, with a bit of free-form structure to group properties into relevant groups. Long-term we might even need to split it up into different spec files to keep a good overview. Docbook is indeed hard to read and write when it comes to such tables. However I like having the properties documented in the DRM core documentation. Maybe we could come up with a simpler text format that would be transformed into docbook when compiling the documentation ? Does this mean we need to create comment block with Doc: drm properties style section in each driver where drm properties are instantiated. And then in drm.tmpl collect all these using !P escape sequence? How do create table out of these across all drivers? I don't have a strong preference here. Documenting properties in source code comments would be fine, so would an external central documentation file in a non Docbook format. For the record I'm personally fine with using Docbook as in this patch :-) If we decide to go for property documentation inside the source code then I believe we'll have to create our own format, as creating a properties table from kerneldoc information extracted from comments is probably not possible. -- Regards, Laurent Pinchart ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
