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? > 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 > > _______________________________________________ > desktop-devel-list mailing list > desktop-devel-list@gnome.org > https://mail.gnome.org/mailman/listinfo/desktop-devel-list
_______________________________________________ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list