[osiris-devel] 3.0.4-current development documentation?
Alexei Roudnev
Alexei_Roudnev at exigengroup.com
Sun Feb 22 16:39:11 EST 2004
Sorry, Tom. Of course, it is not a bad idea, and it is only a _disk space_ issue.
But remember, that 99% of all users do not need your xml, dtd etc - they need plain text on the screen, so pdf file or html file looks quite
enough for the _binary_ distribution. Anyway, it's not important, I have not any objections.
Doxigen (JavaDoc etc) is quite another issue. In real projects, it is not _redundant_. Reason is very simple:
- documentation is edited and corrected by _technical editor_, _technical corrector_ etc;
- you do not want them to edit a sources;
- you do not want to have a include file, having 90% of the documentation and 10% of the source code.
But, on the other hand, you want to write documentation in such style, that it is auto-referenced - if I write out API call, I'd like to see html link on this place, not a plain text.
As a result, after a few experiments, we added special suffix, .dxf, to the list of source files, and moved all _BIG_ pieces of documentation into it. For example, if we have some subsystem, we put subsystem description, with a simple usage example, here, and enlist all API interfaces in the end.
Remember, that user is not looking for the 'CLASS' or 'ABC::xxx' function; he is looking for, for example, 'How can I create, maintain and delete a thread and set/unset mutex, when I use this system'.
It is very important. Documentation have a 3 file types -
- plain html documents, used as a index-I level;
- dxf files, working as an introduction to the subsystems, servers, config files etc, and used as a index-II level;
- .cpp and .h files, used to generate detailed references to the api functions.
It worked fine. I saw the same approach in a few other projects (QT, for example) - do not say _I have a doxigen and it provides a documentation_ (because it provides a garbage) but say _I have a documentation, and I use doxigen to document functions and classes, so I am 100% sure than they are documented up-to-date, and I use dxf files for other documentation, so they are processed by technical editor and corrector, are written in free-lance style, do not create a mess in include directories, and uses doxigen class and method description for detailed references_.
Just again - Doxigen or JavaDoc provides, by themself, a mess of 90% useless reference manuals.
Here is an example (I used abandoned project. btw - EOL project is abandoned, but exists and in working conditions, if someone is interested in multi-platform middleware, we can try to put life into it).
Level I document - plain html:
--------------------------------------------------------------------------------
Exigen Middleware: Exigen Object Library (EOL) Documentation
Release Notes.
--------------------------------------------------------------------------------
1. Quick Start
Introduction and functional overview
EOL Security design
EOL Cookbook
a.. Sample Chat Application: Introduction
b.. Client EODL mapping and implementation
c.. Server EODL mapping and implementation
d.. Object Lifecycle Usage
e.. Creating evolving designs: multiple versions of the simple chat application
--------------------------------------------------------------------------------
2. EOL User's Guide
a.. EOL Naming Service User's Guide
b.. Dynamic type usage
c.. EIO Introduction and MT Guide
d.. ELS User's Guide
e.. ETP User's Guide
--------------------------------------------------------------------------------
Level 2 document - .dxf file.
Main Page Modules Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages
--------------------------------------------------------------------------------
EOL Naming Service : User's Guide
Introduction
EOL Objects can be of two types:
a.. well known - with well known object references which can be written out before object is running;
b.. normal - which contains signature based on the random seed and must be registered before any client can subscribe to them.
Naming service provides:
a.. registration (named 'binding') of the server objects;
b.. resolution of the objects by their names;
c.. basic access control;
d.. basic redundancy for the objects.
EOL Naming Service API
Usually programs should not bother about naming service and work with Name Service directly, but should use EOL Naming Service API instead. This API allows:
a.. Register server object by its name (EOLServerObject::makeBinding()) for the full or restricted access. Server object can be registered a few times with the different names and different access rights, and can be unregistered as well. A few servers can register objects with the same names that allows to set up redundant configurations.
b.. Subscribe to the object by its name (in synchronous or asynchronous mode). If a few servers were registered, subscription will choose the nearest server and skip servers that do not answer.
c.. Use ENSNameContext, EOLStaticNameContext, EOLResolver and EOLBinding classes for more specific tasks.
--------------------------------------------------------------------------------
=================
<snip>
Geez O'pete !!!! You are killing me.
XML is easily extensible to almost any other format with a standard DTD. AND
can be utilized and referenced with readbility formulas(Dale-Chall, Flesch)
so that even general user documentation can be compiled very quickly.
i.e. KDE document sourcing, etc.....
As for LaTeX ----- is very easy to transform this format to desktop reference
materials, for various different platforms. Given that Osiris is not system
dependant; this makes very good sense.
BTW --- doxygen "only" files are redundant. It would be considerably easier to
just correctly format the comments directly into the sources. Why comment
source code to make it incompatible with doxygen, then make another file for
the same data that is compiled by said document.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)
iD8DBQFAOHBZQT2komo99ukRAmNdAKCM7VkhSvrBNkI+/E7MZtq2YTY08ACgvwYI
9XDt+0aaIZr/keNomxrnrqg=
=dMhp
-----END PGP SIGNATURE-----
_______________________________________________
osiris-devel mailing list
osiris-devel at lists.shmoo.com
https://lists.shmoo.com/mailman/listinfo/osiris-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.shmoo.com/pipermail/osiris-devel/attachments/20040222/31084f82/attachment.htm
More information about the osiris-devel
mailing list