On Tuesday 24 June 2008 13:58, Lukas Ocilka wrote:
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.
Lukas, just to clarify: I am not blaming you for the lack of documentation of such essential things. Maintaining documentation generation (which is what you agreed to AFAIK) is a one important task. This does not include writing documentation for all the things where docs are missing. Writing or adding missing docs is the responsibility of the author of the respective piece of software or of the maintainer. I find it really sad to see that in all the years of using YCP nobody found it important enough to write decent documentation to such basic things as YCP built-ins or SCR agents. IMHO it is the first and most important thing to do when writing a new piece of software to describe what it should do. That's the specification, the guideline for coding. Done properly, this should serve a dual purpose as documentation. I've been doing this for years and years, and I always found that approach worthwhile. Not only does that generate documentation as a nice side effect, it also forces you to think about what that function should do, what the parameters are, how fringe cases (NULL or nil) are handled, and what values are returned. Example: http://svn.opensuse.org/svn/yast/trunk/libyui/src/YSelectionWidget.h IMHO this is the way to go for C++ as well as for YCP or for other things that have only the most remote chance to be used from anybody else (but I do it also for functions that are used purely internally). IMHO this is so natural that I am wondering how others are coping with their programming interfaces. How would I know in six weeks from now what on earth some function does, what parameters it expects, what it returns in all cases? How are the authors of all those undocumented SCR agents doing it? Is there some documentation hidden in some other place? I can't believe it's all throw-away code - written just for here and now, meant to be reengineered for every tiny little change. There must be some methodical approach to it that I just don't see. So how does it work?
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...
Sure. I could. But frankly, why would I want to reward those who didn't do the most basic requirement of their job in the first place? Documenting is part of the development process. This might sound harsh, but IMHO those who don't do it just don't do their job right - it's just being lazy. And pressing release milestones is something that affects us all, so that cannot hold as an excuse for all eternity - even less so when summarizing what a function does is to all intents and purposes a time saver, not additional time spent.
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/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...
The most basic clicking through that agents list (that's what I did in my previous mail) will show that the great majority of them has little or no documentation.
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_Easie r_(Better)
Feel free to add yourself to the project if you are willing to help.
No, I am not going to write other people's documentation on top of all the
stuff I already documented. Not only no, but "hell, no". ;-}
CU
--
Stefan Hundhammer