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.ht...
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@suse.de> 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@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org