On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote:
On Mon, Feb 02, 2015 at 08:05:00AM +0000, Philip Withnall wrote:It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions.Can we assume that most still needs to be actioned? Also interested what discussions there were during the hackfest to improving this. E.g. Should we maybe reach out to our advisory board? Some things mentioned lack of documentation. So with DX hackfest and documentation at same time I also wonder if there were any possibilities to improve this.
Some of the items need actioning via bugs, which I will sort out. Some
of them have already been fixed (either as part of the client work by
Collabora, or by others in the time since). Some of them are unfixable,
and can only be used as general guidelines for trying to avoid such
problems in future (e.g. in new API designs).
What do you mean by reaching out to the advisory board? Reaching out for
further feedback from them as downstreams, or reaching out for resources
to fix such issues? I think the former would be interesting. I’m not
sure the latter is worth their time, since it’s a very loosely defined
goal.
There were some DX–documentation discussions, although I wasn’t involved
in all of them so I can’t report fully. One interesting discussion came
up with a set of requirements for any replacement for gtk-doc:
1. Do not want to write XML in documentation comments. Too painful, and
a steep learning curve.
2. No version control program (but wikis’ version control is fine). Too
much of a barrier for contribution.
3. No waiting for review of documentation changes — post-hoc gives a
much lower barrier to contribution instead.
4. Instant gratification: documentation changes should be visible
instantly, rather than waiting 6 months for a GNOME release before
the docs hit developer.gnome.org.
5. Documents need to be available offline in Devhelp.
6. Devhelp needs to give you documentation for the version of the
library you’re using (e.g. in JHBuild), not the version installed on
your system, which is invariably outdated.
7. Automatically generate documentation from annotations as much as
possible (e.g. eliminate ‘Free return value with g_free()’ in favour
of (transfer full)).
8. Topic-based help which can be reorganised dynamically; eliminate
in-order Docbook indexes. Basically the Mallard approach for
reference documentation.
9. Don’t put big code examples in C comments; move them to separate C
files instead, which can be compiled stand-alone. Have a way of
limiting what gets rendered in the docs, plus a link to the full
source.
10. Don’t parse C with regexps; use documentation from GIR files, and
allow g-ir-scanner to do the C parsing legwork.
11. One page per function, rather than one page containing a
loosely-associated jumble of functions (see also: point #8).
12. Include documentation for enums which are specific to a particular
function in that function’s documentation.
13. The system should actually be maintained. (This isn’t a negative
against gtk-doc, which is well maintained. It’s a negative against
all the other replacements for it which are not.)
Note that this is a set of requirements for *any* replacement, whether
it be gtk-doc version 2, or any one of the many replacements people have
prototyped. We did not discuss a plan for actually writing a new
documentation tool for API references.
Ryan, does that sound like everything we discussed? These are typed up
from my notes, so if anything needs clarification, please say.
Philip
Attachment:
signature.asc
Description: This is a digitally signed message part