Stefan Hundhammer wrote:
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.
That's what I actually blame YaST-core maintainer for. Anyway, anybody who has write access to our SVN can change it and add some missing pieces, e.g., explanatory examples. You might have seen some of my commits that were just adding comments to some other's code. You can do the same... everybody can...
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
cd source/core/libycp/src svn blame YCPBuiltinList.cc YCPBuiltinString.cc YCPBuiltinTerm.cc
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...
Anas :)? heh
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)
Report a bug or even fix it ;) I usually do it that way...
If we want community developers to contribute and use our infrastructure, that infrastructure must be reasonably usable. And that starts with documentation.
That's also why I've added this project: Make YaST Documentation Better http://en.opensuse.org/YaST/Research/Make_Building_YaST_Documentation_Easier...) Feel free to add yourself to the project if you are willing to help. Bye Lukas