////////////////////////////////////////////////////////////////////////////////
/// @brief naming conventions in ArangoDB
///
/// @file
///
/// DISCLAIMER
///
/// Copyright 2012 triagens GmbH, Cologne, Germany
///
/// Licensed under the Apache License, Version 2.0 (the "License");
/// you may not use this file except in compliance with the License.
/// You may obtain a copy of the License at
///
///     http://www.apache.org/licenses/LICENSE-2.0
///
/// Unless required by applicable law or agreed to in writing, software
/// distributed under the License is distributed on an "AS IS" BASIS,
/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
/// See the License for the specific language governing permissions and
/// limitations under the License.
///
/// Copyright holder is triAGENS GmbH, Cologne, Germany
///
/// @author Jan Steemann
/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
/// @page NamingConventions Naming Conventions in ArangoDB
///
/// The following naming conventions should be followed by users when creating
/// collections and documents in ArangoDB.
///
/// @section CollectionNames Collection names
///
/// Users can pick names for their collections as desired, provided the following
/// naming constraints are not violated: 
///
/// - Collection names must only consist of the letters @LIT{a} to @LIT{z} 
///   (both in lower and upper case), the numbers @LIT{0} to @LIT{9}, the
///   the underscore (@LIT{_}), or the dash (@LIT{-}) symbol. This also means that
///   any non-ASCII collection names are not allowed.
///
/// - Regular collection names must start with a letter, and not a number, the 
///   underscore or the dash symbol. Collection names starting with either a number,
///   an underscore or a dash are considered to be system collections that
///   are for ArangoDB's internal use only. System collection names should not be
///   used by end users for their own collections.
///
/// - The maximum allowed length of a collection name is 64 bytes.
///
/// - Collection names are case-sensitive.
///
/// @section AttributeNames Attribute names 
///
/// Users can pick attribute names for document keys as desired, provided the
/// following attribute naming constraints are not violated:
///
/// - Attribute names starting with an underscore are considered to be system
///   attributes for ArangoDB's internal use. Such attribute names are already used
///   by ArangoDB for special purposes, e.g. @LIT{_id} is used to contain a
///   document's id, @LIT{_rev} is used to contain the revision number, and the
///   @LIT{_from} and @LIT{_to} attributes are used within edge collections.
///   More system attributes may be added in the future without further notice
///   so end users should not use attribute names starting with an underscore
///   for their own attributes.
///
/// - Attribute names should not start with the at-mark (@LIT{\@}). The at-mark
///   at the start of attribute names is reserved in ArangoDB for future use cases.
///
/// - Theoretically, attribute names can include punctuation and special characters
///   as desired, provided the name is a valid UTF-8 string. 
///   For maximum portability, special characters should be avoided though. 
///   For example, attribute names may
///   contain the dot symbol, but the dot has a special meaning in Javascript and
///   also in AQL, so when using such attribute names in one of these languages, the
///   attribute name would need to be quoted by the end user. This will work but
///   requires more work so it might be better to use attribute names which don't
///   require any quoting/escaping in all languages used. This includes languages
///   used by the client (e.g. Ruby, PHP) if the attributes are mapped to object
///   members there.
///
/// - ArangoDB does not enforce a length limit for attribute names. However, long
///   attribute names may use more memory in result sets etc. Therefore the use
///   of long attribute names is discouraged.
///
/// - As ArangoDB saves document attribute names separate from the actual document
///   attribute value data, the combined length of all attribute names for a document 
///   must fit into an ArangoDB shape structure. The maximum combined names length
///   is variable and depends on the number and data types of attributes used.
///
/// - Attribute names are case-sensitive.
////////////////////////////////////////////////////////////////////////////////

// Local Variables:
// mode: c++
// mode: outline-minor
// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
// End: