Mailinglist Archive: yast-devel (116 mails)

< Previous Next >
Re: [yast-devel] YaST Workshop 2008
  • From: Lukas Ocilka <lukas.ocilka@xxxxxxx>
  • Date: Tue, 24 Jun 2008 13:58:47 +0200
  • Message-id: <4860E177.8010309@xxxxxxx>
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.html

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_(Better)

Feel free to add yourself to the project if you are willing to help.

Bye
Lukas

< Previous Next >
Follow Ups