Mailinglist Archive: yast-devel (116 mails)

< Previous Next >
Re: [yast-devel] YaST Workshop 2008
  • From: Stefan Hundhammer <sh@xxxxxxx>
  • Date: Tue, 24 Jun 2008 13:02:42 +0200
  • Message-id: <200806241302.42605.sh@xxxxxxx>
On Monday 23 June 2008 10:58, Lukas Ocilka wrote:
YCP builtins are documented and would have useful examples if anybody
cared when writing them:

http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-YaSTReference.html

AFAICS that documentation is just the bare minimum - little more than the
function name. And the examples are not really explanatory.

Some newer built-ins are documented a lot better (e.g., splitstring()). But
that's the exceptional case.

Worst, the most powerful built-ins are not documented in a way any novice YCP
developer can make sense of anything:

http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_filter.html
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_find.html
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_foreach.html
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_listmap.html
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_maplist.html

Some docs lack basic things like "will the original object be modified?"
(old-time YCP hackers of course know, but can we expect that from newbies?):

http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_remove.html

And why a built-in called setcontains() handles lists, not sets, is completely
unclear:

http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_setcontains.html


SCR Agents are documented quite well

Uh - no. I find the documentation of most of them utterly useless.

http://forgeftp.novell.com/yast/doc/SL11.0/scr/1.anyxml.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/2.audio.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/3.autoyast2.desktop.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/5.backup.file_append.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/9.bootloader.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/10.complain.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/14.cron.html
...

(only ~1 out of 10 has anything meaningful at all)


If we want community developers to contribute and use our infrastructure, that
infrastructure must be reasonably usable. And that starts with documentation.


CU
--
Stefan Hundhammer <sh@xxxxxxx> Penguin by conviction.
YaST2 Development
SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg)
Nürnberg, Germany
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: yast-devel+help@xxxxxxxxxxxx

< Previous Next >
Follow Ups