summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Vrátil <dvratil@kde.org>2016-08-09 00:06:39 (GMT)
committerDaniel Vrátil <dvratil@kde.org>2016-08-09 00:11:13 (GMT)
commitaff413b533c98bc4e6122ee1f8c47be8853ff069 (patch)
tree5251e916f72ba459514c75e79eede211d43eb586
parent330b9a5fb651ca22b93362db3b6099d46b561cf0 (diff)
Improve the documentation markup
-rw-r--r--README.md8
-rw-r--r--docs/client_libraries.md44
-rw-r--r--docs/history.md6
-rw-r--r--docs/internals.md4
-rw-r--r--docs/server.md48
5 files changed, 55 insertions, 55 deletions
diff --git a/README.md b/README.md
index 5c9fdb2..d1df70c 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Akonadi
+# Akonadi #
Akonadi aims to be an extensible cross-desktop storage service for PIM data
and meta data providing concurrent read, write, and query access.
@@ -7,17 +7,17 @@ It provides unique desktop-wide object identification and retrieval.
Akonadi framework provides two parts: the server, and client libraries to
access the data managed by the server.
-## Client Libraries
+## Client Libraries ##
If you are an application developer and want to access and interact with data
stored in Akonadi, you should read the [Akonadi client libraries documentation](@ref client_libraries).
-## Akonadi Server
+## Akonadi Server ##
If you are interested in working on the Akonadi framework itself, you can read
more about the internals of the Akonadi Server and the protocol in the
[Akonadi server documentation](@ref server).
-## History
+## History ##
You can also read a bit more about [history of Akonadi](@ref history)
diff --git a/docs/client_libraries.md b/docs/client_libraries.md
index 6b9885c..0c86f00 100644
--- a/docs/client_libraries.md
+++ b/docs/client_libraries.md
@@ -1,11 +1,11 @@
-# Akonadi client libraries {#client_libraries}
+# Akonadi client libraries # {#client_libraries}
[TOC]
Akonadi client libraries consist of three libraries that provide tools to access
the Akonadi PIM data server: AkonadiCore, AkonadiWidgets and AkonadiAgentBase.
All processes accessing Akonadi, including those which communicate with a remote
-server "[agents](@ref agents)", are considered clients.
+server [agents](@ref agents), are considered clients.
<!--
Additional information about Akonadi:
@@ -21,7 +21,7 @@ Tools for developers:
- <a href="https://bugs.kde.org/buglist.cgi?query_format=advanced&product=Akonadi&component=libakonadi&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">Bugtracker</a>
//-->
-# Akonadi Objects {#objects}
+# Akonadi Objects # {#objects}
Akonadi works on two basic object types: collections and items.
@@ -41,7 +41,7 @@ Both items and collections are identified by a persistent unique identifier.
Also, they can contain arbitrary attributes (derived from Akonadi::Attribute) to
attach general or application specific meta data to them.
-# Collection retrieval and manipulation {#collections}
+# Collection retrieval and manipulation # {#collections}
A collection is represented by the Akonadi::Collection class.
@@ -64,7 +64,7 @@ type of PIM items. Akonadi::CollectionPropertiesDialog provides an extensible pr
dialog for collections. Often needed KAction for collection operations are provided by
Akonadi::StandardActionManager.
-# PIM item retrieval and manipulation {#items}
+# PIM item retrieval and manipulation # {#items}
PIM items are represented by classes derived from Akonadi::Item.
Items can be retrieved using Akonadi::ItemFetchJob.
@@ -80,7 +80,7 @@ Akonadi::ItemModel provides a self-updating model class which can be used to dis
of a collection. Akonadi::ItemView is the base class for a corresponding view. Often needed KAction
for item operations are provided by Akonadi::StandardActionManager.
-# Low-level access to the Akonadi server {#jobs}
+# Low-level access to the Akonadi server # {#jobs}
Accessing the Akonadi server is done using job classes derived from Akonadi::Job. The
communication channel with the server is provided by Akonadi::Session.
@@ -95,13 +95,13 @@ There also is Akonadi::TransactionSequence which can be used to automatically gr
a set of jobs into a single transaction.
-# Change notifications (Monitor) {#monitor}
+# Change notifications (Monitor) # {#monitor}
The Akonadi::Monitor class allows you to monitor specific resources,
collections and PIM items for changes. Akonadi::ChangeRecorder augments this
by providing a way to record and replay change notifications.
-# PIM item serializer {#serializer}
+# PIM item serializer # {#serializer}
The class Akonadi::ItemSerializer is responsible for converting between the stored (binary) representation
of a PIM item and the objects used to handle these items provided by the corresponding libraries (kabc, kcal, etc.).
@@ -109,7 +109,7 @@ of a PIM item and the objects used to handle these items provided by the corresp
Serializer plugins allow you to add support for new kinds of PIM items to Akonadi.
Akonadi::ItemSerializerPlugin can be used as a base class for such a plugin.
-# Agents and Resources {#resource}
+# Agents and Resources # {#resource}
Agents are independent processes that watch the Akonadi store for changes and react to them if necessary.
Example: The Akonadi Indexing Agent is an agent that watches Akonadi for new emails, calendar events, etc.,
@@ -139,7 +139,7 @@ is not necessarily the same (e.g. the Kolab resource supports contacts and event
in the same folder).
-# Integration in your Application {#integration}
+# Integration in your Application # {#integration}
Akonadi::Control provides ways to ensure that the Akonadi server is running, to monitor its availability
and provide help on server-side errors. A more low-level interface to the Akonadi server is provided
@@ -151,7 +151,7 @@ look and feel across applications.
This library provides classes for KDE applications to communicate with the Akonadi server. The most high-level interface to Akonadi is the Models and Views provided in this library. Ready to use models are provided for use with views to interact with a tree of collections, a list of items in a collection, or a combined tree of Collections and items.
-## Collections and Items {#collections_and_items}
+## Collections and Items ## {#collections_and_items}
In the Akonadi concept, Items are individual objects of PIM data, e.g. emails, contacts, events, notes etc. The data in an item is stored in a typed payload. For example, if an Akonadi Item holds a contact, the contact is available as a KABC::Addressee:
@@ -175,7 +175,7 @@ col.setContentMimetypes({ Akonadi::Collection::mimeType(),
This system makes it simple to create PIM applications. For example, to create an application for viewing and editing events, you simply need to tell %Akonadi to retrieve all items matching the mimetype 'text/calendar'.
-## Convenience Mimetype Accessors {#convenience_mimetype_accessors}
+## Convenience Mimetype Accessors ## {#convenience_mimetype_accessors}
In order to avoid typos, improve readability, and to encapsulate the correct mimetypes for particular pim items, many of the standard classes have an accessor for the kind of mimetype the can handle. For example, you can use KMime::Message::mimeType() for emails, KABC::Addressee::mimeType() for contacts etc. It makes sense to define a similar static function in your own types.
@@ -185,7 +185,7 @@ col.setContentMimetypes({ Akonadi::Collection::mimeType(),
KMime::Message::mimeType() });
~~~~~~~~~~~~~
-## Models and Views {#models_and_views}
+## Models and Views ## {#models_and_views}
Akonadi models and views are a high level way to interact with the Akonadi server. Most applications will use these classes. See the EntityTreeModel documentation for more information.
Models provide an interface for viewing, deleting and moving Items and Collections. New Items can also be created by dropping data of the appropriate type on a model. Additionally, the models are updated automatically if another application changes the data or inserts or deletes items etc.
@@ -414,7 +414,7 @@ The SelectionProxyModel orders its items in the same top-to-bottom order as they
Details on the actual implementation of lazy population are described on [this page](@ref internals).
-# Jobs and Monitors {#jobs_and_monitors}
+# Jobs and Monitors # {#jobs_and_monitors}
The lower level way to interact with Akonadi is to use Jobs and Monitors (This is what models use internally). Jobs are used to make changes to akonadi, and in some cases (e.g., a fetch job) emit a signal with data resulting from the job. A Monitor reports changes made to the data stored in Akonadi (e.g., creating, updating, deleting or moving an item or collection ) via signals.
@@ -422,14 +422,14 @@ Typically, an application will configure a monitor to report changes to a partic
Most applications will use some of the low level api for actions unrelated to a model-tree view, such as creating new items and collections.
-# Tricky details {#tricky_details}
+# Tricky details # {#tricky_details}
-## Change Conflicts {#change_conflicts}
+## Change Conflicts ## {#change_conflicts}
It is possible that while an application is editing an item, that item gets updated in akonadi. Akonadi will notify the application that that item has changed via a Monitor signal. It is the responsibility of the application to handle the conflict by for example offering the user a dialog to resolve it. Alternatively, the application could ignore the dataChanged signal for that item, and will get another chance to resolve the conflict when trying to save the result back to akonadi. In that case, the ItemModifyJob will fail and report that the revision number of the item on the server differs from its revision number as reported by the job. Again, it is up to the application to handle this case.
This is something that every application using akonadi will have to handle.
-## Using Item::Id or Collection::Id as an identifier {#using_id_as_an_identifier}
+## Using Item::Id or Collection::Id as an identifier ## {#using_id_as_an_identifier}
Items and Collections have a id() member which is a unique identifier used by akonadi. It can be useful to use the id() as an identifier when storing Collections or Items.
@@ -473,7 +473,7 @@ qstring getremoteidbyinternalidentifier(qint64 internalidentifier)
~~~~~~~~~~~~~
-### Unordered Lists {#unordered_lists}
+### Unordered Lists ### {#unordered_lists}
Collection and Item both provide a ::List to represent groups of objects. However the objects in the list are usually not ordered in any particular way, even though the API provides methods to work with an ordered list. It makes more sense to think of it as a Set instead of a list in most cases.
For example, when using an ItemFetchJob to fetch the items in a collection, the items could be in any order when returned from the job. The order that a Monitor emits notices of changes is also indeterminate. By using a Transaction however, it is sometimes possible to retrieve objects in order. Additionally, using s constructor overload in the CollectionFetchJob it is possible to retrieve collections in a particular order.
@@ -492,19 +492,19 @@ Collection::List getCollections(const QList<Collection::Id> &idsToGet)
}
~~~~~~~~~~~~~
-# Resources {#resources}
+# Resources # {#resources}
The KDEPIM module includes resources for handling many types of PIM data, such as imap email, vcard files and vcard directories, ical event files etc. These cover many of the sources for your PIM data, but in the case that you need to use data from another source (for example a website providing a contacts storage service and an api), you simply have to write a new resource.
http://techbase.kde.org/Development/Tutorials/Akonadi/Resources
-# Serializers {#serializers}
+# Serializers # {#serializers}
Serializers provide the functionality of converting raw data, for example from a file, to a strongly typed object of PIM data. For example, the addressee serializer reads data from a file and creates a KABC::Addressee object.
New serializers can also easily be written if the data you are dealing with is not one of the standard PIM data types.
-# Implementation details {#implementation_details}
+# Implementation details # {#implementation_details}
-## Updating Akonadi Models {#updating_models}
+## Updating Akonadi Models ## {#updating_models}
NOTE: The details here are only relevant if you are writing a new view using EntityTreeModel, or writing a new model.
diff --git a/docs/history.md b/docs/history.md
index f3d4c20..2ccb74b 100644
--- a/docs/history.md
+++ b/docs/history.md
@@ -1,6 +1,6 @@
-# Historical background {#history}
+# Historical background # {#history}
-## General
+# General #
During the last 5 years, after the release of KDE 3.0, the requirements of our users
have constantly increased. While it was sufficient that our PIM solution was able to handle 100 contacts,
@@ -17,7 +17,7 @@ came to the conclusion that a service is needed which acts as a local cache on t
and provides search facilities. The name Akonadi comes from a divinity from Ghana and was chosen since
all other nice names were already used by other projects on the Internet ;)
-## Problems with the implementation of KDE 3.x
+# Problems with the implementation of KDE 3.x #
Before digging into the internals of Akonadi, we want to take a look at the implementation of the
old KDE PIM libraries to understand the problems and conceptual shortcomings.
diff --git a/docs/internals.md b/docs/internals.md
index 1a7ebef..0633ae8 100644
--- a/docs/internals.md
+++ b/docs/internals.md
@@ -1,6 +1,6 @@
-# Internals documentation for Akonadi developers {#internals}
+# Internals documentation for Akonadi developers # {#internals}
-## Lazy Model Population
+## Lazy Model Population ##
NOTE: This page is not part of the Akonadi API. It is provided as internal documentation for Akonadi maintainers. It was originally a blog post here: http://steveire.wordpress.com/2009/10/06/cache-invalidation-in-akonadi-models/
@internal
diff --git a/docs/server.md b/docs/server.md
index ee8a5a1..194765f 100644
--- a/docs/server.md
+++ b/docs/server.md
@@ -1,4 +1,4 @@
-# Akonadi Server {#server}
+# Akonadi Server # {#server}
[TOC]
@@ -9,7 +9,7 @@ working on the Akonadi server itself.
For additional information, see the <a href="http://community.kde.org/KDE_PIM/Akonadi">Akonadi website</a>.
-## Architecture
+## Architecture ##
<img src="http://community.kde.org/images.community/8/8e/Akonadi_Architecture.png"/>
@@ -19,7 +19,7 @@ The Akonadi framework uses a client/server architecture. The Akonadi server has
* Provide change notifications and conflict detection
* Support offline change recording and change replay for remote data
-## Design Principles
+## Design Principles ##
The Akonadi architecture is based on the following four design principles:
@@ -44,7 +44,7 @@ The Akonadi architecture is based on the following four design principles:
back-end itself must be asynchronous. You can easily provide a synchronous convenience
for the application developer; the back-end, however, must communicate asynchronously.
-## Components
+## Components ##
The Akonadi server itself consists of a number of components:
* The Akonadi control process (`akonadi_control`). It is responsible for managing all other server components and Akonadi agents.
* The Akonadi server process (`akonadiserver`). The actual data access and caching server.
@@ -55,7 +55,7 @@ The Akonadi server itself consists of a number of components:
* The Akonadi protocol library (`libakonadiprotocolinternals`), Contains protocol definitions and protocol parsing methods
useful for client implementations.
-### The Akonadi server process
+### The Akonadi server process ###
The Akonadi server process (`akonadiserver`) has the following tasks:
* Provide a transaction-safe data store.
@@ -64,7 +64,7 @@ The Akonadi server process (`akonadiserver`) has the following tasks:
* Manage virtual collections representing search results.
* Provide change notifications for all known Akonadi objects over D-Bus.
-### The Akonadi server control process
+### The Akonadi server control process ###
The Akondi control process (\c akonadi_control) has the following tasks:
* Manage and monitor the other server processes.
@@ -73,12 +73,12 @@ The Akondi control process (\c akonadi_control) has the following tasks:
* Provide D-Bus API to manage agents.
* Provide change notifications on agent types and agent instances.
-## Objects and Data Types
+## Objects and Data Types ##
The Akonadi server operates on two basic object types, called items and collections. They are comparable to files and directories
and are described in more detail in this section.
-## Akonadi Items
+## Akonadi Items ##
An item is a generic container for whatever you want to store in Akonadi (eg. mails,
events, contacts, etc.). An item consists of some generic information (such as identifier,
@@ -86,7 +86,7 @@ mimetype, change date, flags, etc.) and a set of data fields, the item parts. It
are independent of the type of stored data, the semantics of the actual content is only
known on the client side.
-## Items Parts
+## Items Parts ##
Akonadi items can have one or more parts, e.g. an email message consists of the
envelope, the body and possible one or more attachments. Item parts are identified
@@ -94,20 +94,20 @@ by an identifier string. There are a few special pre-defined part identifiers (A
ENVELOPE, etc.), but in general the part identifiers are defined by the type specific
extensions (ie. resource, serializer plugin, type specific client library).
-## Item Tags
+## Item Tags ##
Tags are self-contained entities stored in separate database table. A tag is a
relation between multiple items. Tags can have different types (PLAIN, ...) and applications
can define their own type to describe application-specific relations. Tags can also have
attributes to store additional metadata about the relation the tag describes.
-## Payload Data Serialization
+## Payload Data Serialization ##
Item payload data is typically serialized in a standard format to ensure interoperability between different
client library implementations. However, the %Akonadi server does not enforce any format,
payload data is handled as an opaque binary blob.
-## Collections
+## Collections ##
Collections are sets of items. Every item is stored in exactly one
collection, this is sometimes also referred to as the "physical" storage location of the item.
@@ -120,7 +120,7 @@ collections, thus defining a collection tree.
Collections are uniquely identified by their identifier in
contrast to their path, which is more robust with regard to renaming and moving.
-## Collection Properties
+## Collection Properties ##
Every collection has a set of supported content types.
These are the mimetypes of items the collection can contain.
@@ -137,7 +137,7 @@ used for incremental synchronization. Evaluation of such attributes is the respo
of client implementations, the %Akonadi server does not interpret properties
other than content types and cache policies.
-## Collection Tree
+## Collection Tree ##
There is a single collection tree in Akonadi, consisting of several parts:
@@ -169,9 +169,9 @@ Example:
...
-## Object Identification
+## Object Identification ##
-### Unique Identifier
+### Unique Identifier ###
Every object stored in %Akonadi (collections and items) has a unique
identifier in the form of an integer value. This identifier cannot be changed in
@@ -179,7 +179,7 @@ any way and will stay the same, regardless of any modifications to the referred
object. A unique identifier will never be used twice and is globally unique,
therefore it is possible to retrieve an item without knowing the collection it belongs to.
-### Remote Identifier
+### Remote Identifier ###
Every object can also have an optional so-called remote identifier. This is an
identifier used by the corresponding resource to identify the object on its
@@ -191,30 +191,30 @@ Special case applies for Tags, where each tag can have multiple remote IDs. This
however opaque to resources as each resource is shown only the remote ID that it had
provided when inserting the tag into Akonadi.
-### Global Identifier
+### Global Identifier ###
Every item can has also so called GID, an identifier specific to the content (payload)
of the item. The GID is extracted from the payload by client serializer when storing the
item in Akonadi. For example, contacts have vCard "UID" field as their GID, emails can
use value of "Message-Id" header.
-## Communication Protocols
+## Communication Protocols ###
For communication within the Akonadi server infrastructure and for communication with Akonadi clients, two communication technologies are used:
* D-Bus Used for management tasks and change notifications.
* ASAP (Akonadi Server Access Protocol), used for high-throughput data transfer. ASAP is based on the well-known IMAP protocol (RFC 3501) which has been proven it's ability to handle large quantities of data in practice already.
-## Interacting with Akonadi
+## Interacting with Akonadi ##
There are various possibilities to interact with Akonadi.
-### Akonadi Client Libraries
+### Akonadi Client Libraries ###
Accessing the Akonadi server using the ASAP and D-Bus interfaces directly is cumbersome.
Therefore you'd usually use a client library implementing the low-level protocol handling
and providing convenient high-level APIs for Akonadi operations.
-### Akonadi Agents
+### Akonadi Agents ###
Akonadi agents are processes which are controlled by the Akonadi server itself. Agents typically
operate autonomously (ie. without much user interaction) on the objects handled by Akonadi, mostly
@@ -226,9 +226,9 @@ The most important ones are the so-called resource agents.
Resource agents are connectors that provide access to data from an external source, and replay local changes
back to their corresponding backend.
-## Implementation Details
+## Implementation Details ##
-### Data and Metadata Storage
+### Data and Metadata Storage ###
The Akonadi server uses two mechanisms for data storage:
* A SQL databases for metadata and small payload data