Mailinglist Archive: zypp-devel (68 mails)
| < Previous | Next > |
[zypp-devel] missing docs
- From: Jan Kupec <jkupec@xxxxxxx>
- Date: Tue, 29 May 2007 16:20:07 +0200
- Message-id: <465C3697.3000105@xxxxxxx>
Following is a list of docs i had been missing when starting to work on
zypper and later on libzypp:
- library overview - it's purpose and abilities, what it can offer
to the clients (particular functionalities e.g. it can open a
repository and load all the resolvables it contains into some
structure) and how (intro on using pieces of it in the client code).
This should be in one place. [1] and [2] is not enough when it comes
to development of client soft and using libzypp and development of
libzypp itself.
- Vocabulary
- Resolvables - what are these and what kinds of them are there?
FIXED[1].
- (Installation) Source vs. Catalog vs. Repository
terminology explanation.
- code organization - what is what in the source dir tree
(purpose of the code) FIXED[1]
- Class design
- info on the design patterns used (Bridge/Impl and others). If the
newcomer is not familiar with these, he/she's just lost :O)
- compiled zypp devel guide such as:
- use logger (MIL << ...) look HERE for docs
- use exceptions like this (ZYPP_THROW ...) look HERE for docs
- use smart pointers, look HERE for docs
- use THESE patterns, look HERE for docs
- define callback base structs in ZYppCallbacks.h if you need
to communicate or request info from client soft. again, see
HERE for docs.
- etc...
- Class diagram
Martin Vidner and I already started to create one while working on
zypper, using ArgoUML tool. See doc/libzypp.zargo. You can open the
file using ArgoUML, or uznip it and see what's inside. Problem is, the
tool still does not support C++, it's not packaged for SUSE, and,
well, creating a proper class diagram for libzypp is a huge task.
But a printable class diagram with all classes, with at least
inheritance, aggregation and composition relations drawn-in would
be more than useful. We should agree on one tool (maybe the ArgoUML at
last, it is usable) and be responsible for updating it as we modify
the API. NOTE: this should document implementation as well as public
API!
- Code documentation
- documentation of Exceptions - when a particular exception is or
should be thrown
- Resolvables - what does particular resolvable (kind) represent,
what is the corresponding piece of data in metadata (susetags/yum
impl. separately).
- there are probably more, but i can't recall or go through them all
now, we should send a notice about missing docs as we come across
some.
The links:
[1] http://en.opensuse.org/Libzypp/Design
[2] http://en.opensuse.org/Libzypp/Package_Management
Cheers,
jano
--
To unsubscribe, e-mail: zypp-devel+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: zypp-devel+help@xxxxxxxxxxxx
zypper and later on libzypp:
- library overview - it's purpose and abilities, what it can offer
to the clients (particular functionalities e.g. it can open a
repository and load all the resolvables it contains into some
structure) and how (intro on using pieces of it in the client code).
This should be in one place. [1] and [2] is not enough when it comes
to development of client soft and using libzypp and development of
libzypp itself.
- Vocabulary
- Resolvables - what are these and what kinds of them are there?
FIXED[1].
- (Installation) Source vs. Catalog vs. Repository
terminology explanation.
- code organization - what is what in the source dir tree
(purpose of the code) FIXED[1]
- Class design
- info on the design patterns used (Bridge/Impl and others). If the
newcomer is not familiar with these, he/she's just lost :O)
- compiled zypp devel guide such as:
- use logger (MIL << ...) look HERE for docs
- use exceptions like this (ZYPP_THROW ...) look HERE for docs
- use smart pointers, look HERE for docs
- use THESE patterns, look HERE for docs
- define callback base structs in ZYppCallbacks.h if you need
to communicate or request info from client soft. again, see
HERE for docs.
- etc...
- Class diagram
Martin Vidner and I already started to create one while working on
zypper, using ArgoUML tool. See doc/libzypp.zargo. You can open the
file using ArgoUML, or uznip it and see what's inside. Problem is, the
tool still does not support C++, it's not packaged for SUSE, and,
well, creating a proper class diagram for libzypp is a huge task.
But a printable class diagram with all classes, with at least
inheritance, aggregation and composition relations drawn-in would
be more than useful. We should agree on one tool (maybe the ArgoUML at
last, it is usable) and be responsible for updating it as we modify
the API. NOTE: this should document implementation as well as public
API!
- Code documentation
- documentation of Exceptions - when a particular exception is or
should be thrown
- Resolvables - what does particular resolvable (kind) represent,
what is the corresponding piece of data in metadata (susetags/yum
impl. separately).
- there are probably more, but i can't recall or go through them all
now, we should send a notice about missing docs as we come across
some.
The links:
[1] http://en.opensuse.org/Libzypp/Design
[2] http://en.opensuse.org/Libzypp/Package_Management
Cheers,
jano
--
To unsubscribe, e-mail: zypp-devel+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: zypp-devel+help@xxxxxxxxxxxx
| < Previous | Next > |