On Feb 2, 2015 6:37 AM, "Philip Withnall" <philip 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