Re: [Vala] Examples in documentation

[Brian Duffy <brduffy gmail com>]

It looks like the php doc comments section is moderated. When choosing to
add a comment you are directed to a page
<http://www.php.net/manual/add-note.php?sect=function.copy&redirect=http://www.php.net/manual/en/function.copy.php>
that
discusses the rules. That makes sense, otherwise you would wind up getting
all kinds of garbage in the comments section. Assuming Florian was willing
to enable a comments section in Valadoc (big assumption), finding a proper
moderator would be essential to keeping the comments useful . In fact,
finding a willing (and qualified) moderator should be the first step. I'm
guessing that most experienced and qualified Vala developers will be hard
to pin down for such a task.

On the other hand, what if we cloned Valadoc, enabled comments in the docs,
and required developers to login to view the comment enhanced version?
Maybe even require that users belong to vala-list to view it. This should
keep out some of the garbage. We could have a notice prominently displayed
somewhere indicating if comments have been recently added (if they have
been edited etc.) Then the <lethalman's> of the world will probably wind up
looking at them (they just wont be able to help themselves :-)) Maybe (just
maybe) you could get a useful comment section that way and garbage would be
edited out by the experienced developers. I think that would be an
interesting experiment.




On Thu, Nov 8, 2012 at 7:43 AM, Gilzad Hamuni <gilli4 gmx net> wrote:

> Hi all,
>
> maybe it's already there and I missed to see it. Is it possible to have
> some account on an existing valadoc-page, so one could add code-examples
> online rather than working with the markup locally?
>
>
> Knowing that vala is still evolving, I'm facing one issue that probably
> could be solved rapidly.
>
> Except of the given tutorials, if someone wants to implement some feature
> in his application, he either has to
>
> 1) guess how he'd use the vala bindings (requires firm experience with
> glib) or
>
> 2) he has to derive the vala-code from some existing C-code, that is using
> the same library or
>
> 3) crawl through some existing vala-projects that would offer an example,
> somewhere deep inside their source.
>
>
> Now, once a dev has achieved to have some working code, he might want to
> share this as an example, so others will quickly find out how to use
> function X from vapi Y.
>
> Wouldn't it boost vala's easy-to-efficient-ratio, if code-examples were
> attached to the documentation (like on msdn or php.net)? Maybe it could
> be some great advertising, too "Wow, that's just a three-liner!".
>
>
> Sorry if this has been discussed before, I couldn't find anything related
> after a quick search.
>
> Best,
>
> Gilzad
> _______________________________________________
> vala-list mailing list
> vala-list gnome org
> https://mail.gnome.org/mailman/listinfo/vala-list



-- 
Duff