On Mon, 2015-02-02 at 07:55 -0800, Jasper St. Pierre wrote: > > On Feb 2, 2015 6:37 AM, "Philip Withnall" <phi...@tecnocode.co.uk> > wrote: > > > > 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. > > I'm confused. You want both a wiki, and docs embedded in comments? > What are you imagining here?
Sorry, I should have explained that more clearly. Documentation is generated from C comments as at the moment, reformatted, uploaded to developer.gnome.org, and then some kind of online interface can be used to edit the documentation (and possibly add comments to it) with instant gratification. That’s what the first few points are about. There are no requirements covering how these online edits would be fed back into the C comments, but presumably that would happen somehow. The fact that there are no requirements means nobody in the hackfest discussion had strong feelings about how it should be done. Philip
signature.asc
Description: This is a digitally signed message part
_______________________________________________ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
