Complete documentation of the ExifTag class.

4 files changed, 35 insertions, 20 deletions

diff --git a/src/exiv2wrapper.cpp b/src/exiv2wrapper.cpp
index 3ea5ec3..61c0d9a 100644
--- a/src/exiv2wrapper.cpp
+++ b/src/exiv2wrapper.cpp
@@ -488,7 +488,6 @@ ExifTag::ExifTag(const std::string& key, Exiv2::Exifdatum* datum): _key(key)
     const Exiv2::IfdId ifd = _datum->ifdId();
     _type = Exiv2::TypeInfo::typeName(Exiv2::ExifTags::tagType(tag, ifd));
     _name = Exiv2::ExifTags::tagName(tag, ifd);
-    _title = Exiv2::ExifTags::tagTitle(tag, ifd);
     _label = Exiv2::ExifTags::tagLabel(tag, ifd);
     _description = Exiv2::ExifTags::tagDesc(tag, ifd);
     _sectionName = Exiv2::ExifTags::sectionName(tag, ifd);
@@ -515,11 +514,6 @@ const std::string ExifTag::getName()
     return _name;
 }
 
-const std::string ExifTag::getTitle()
-{
-    return _title;
-}
-
 const std::string ExifTag::getLabel()
 {
     return _label;
diff --git a/src/exiv2wrapper.hpp b/src/exiv2wrapper.hpp
index 91a4c77..e2b657d 100644
--- a/src/exiv2wrapper.hpp
+++ b/src/exiv2wrapper.hpp
@@ -48,7 +48,6 @@ public:
     const std::string getKey();
     const std::string getType();
     const std::string getName();
-    const std::string getTitle();
     const std::string getLabel();
     const std::string getDescription();
     const std::string getSectionName();
@@ -61,7 +60,6 @@ private:
     Exiv2::Exifdatum* _datum;
     std::string _type;
     std::string _name;
-    std::string _title;
     std::string _label;
     std::string _description;
     std::string _sectionName;
diff --git a/src/exiv2wrapper_python.cpp b/src/exiv2wrapper_python.cpp
index f2e4831..c9a12b3 100644
--- a/src/exiv2wrapper_python.cpp
+++ b/src/exiv2wrapper_python.cpp
@@ -52,7 +52,6 @@ BOOST_PYTHON_MODULE(libexiv2python)
         .def("_getKey", &ExifTag::getKey)
         .def("_getType", &ExifTag::getType)
         .def("_getName", &ExifTag::getName)
-        .def("_getTitle", &ExifTag::getTitle)
         .def("_getLabel", &ExifTag::getLabel)
         .def("_getDescription", &ExifTag::getDescription)
         .def("_getSectionName", &ExifTag::getSectionName)
diff --git a/src/pyexiv2/exif.py b/src/pyexiv2/exif.py
index 128c6ca..85a288e 100644
--- a/src/pyexiv2/exif.py
+++ b/src/pyexiv2/exif.py
@@ -55,7 +55,19 @@ class ExifValueError(ValueError):
 class ExifTag(ListenerInterface):
 
     """
-    DOCME
+    An EXIF tag.
+
+    Here is a correspondance table between the EXIF types and the possible
+    python types the value of a tag may take:
+     - Ascii: C{datetime.datetime}, C{datetime.date}, C{str}
+     - Byte: C{str}
+     - Short: [list of] C{int}
+     - Long, SLong: [list of] C{long}
+     - Rational, SRational: [list of] L{pyexiv2.utils.Rational}
+     - Undefined: C{str}
+
+    @ivar metadata: the parent metadata if any, or C{None}
+    @type metadata: L{pyexiv2.metadata.ImageMetadata}
     """
 
     # According to the EXIF specification, the only accepted format for an Ascii
@@ -69,7 +81,12 @@ class ExifTag(ListenerInterface):
 
     def __init__(self, key, value=None, _tag=None):
         """
-        DOCME
+        The tag can be initialized with an optional value which expected type
+        depends on the EXIF type of the tag.
+
+        @param key:   the key of the tag
+        @type key:    C{str}
+        @param value: the value of the tag
         """
         super(ExifTag, self).__init__()
         if _tag is not None:
@@ -84,41 +101,45 @@ class ExifTag(ListenerInterface):
 
     @staticmethod
     def _from_existing_tag(_tag):
-        # Build a tag from an already existing _ExifTag
+        # Build a tag from an already existing libexiv2python._ExifTag.
         tag = ExifTag(_tag._getKey(), _tag=_tag)
         tag.raw_value = _tag._getRawValue()
         return tag
 
     @property
     def key(self):
+        """The key of the tag in the form 'familyName.groupName.tagName'."""
         return self._tag._getKey()
 
     @property
     def type(self):
+        """The EXIF type of the tag (one of Ascii, Byte, Short, Long, SLong,
+        Rational, SRational, Undefined)."""
         return self._tag._getType()
 
     @property
     def name(self):
+        """The name of the tag (this is also the third part of the key)."""
         return self._tag._getName()
 
     @property
-    def title(self):
-        return self._tag._getTitle()
-
-    @property
     def label(self):
+        """The title (label) of the tag."""
         return self._tag._getLabel()
 
     @property
     def description(self):
+        """The description of the tag."""
         return self._tag._getDescription()
 
     @property
     def section_name(self):
+        """The name of the tag's section."""
         return self._tag._getSectionName()
 
     @property
     def section_description(self):
+        """The description of the tag's section."""
         return self._tag._getSectionDescription()
 
     def _get_raw_value(self):
@@ -137,7 +158,8 @@ class ExifTag(ListenerInterface):
                 return
         self._value = self._convert_to_python(value)
 
-    raw_value = property(fget=_get_raw_value, fset=_set_raw_value, doc=None)
+    raw_value = property(fget=_get_raw_value, fset=_set_raw_value,
+                         doc='The raw value of the tag as a string (C{str}).')
 
     def _get_value(self):
         return self._value
@@ -168,10 +190,12 @@ class ExifTag(ListenerInterface):
             # Single value
             self._value = value
 
-    value = property(fget=_get_value, fset=_set_value, doc=None)
+    value = property(fget=_get_value, fset=_set_value,
+                     doc='The value of the tag as a python object.')
 
     @property
     def human_value(self):
+        """A human-readable representation of the value of the tag."""
         return self._tag._getHumanValue() or None
 
     # Implement the ListenerInterface
@@ -191,7 +215,7 @@ class ExifTag(ListenerInterface):
         @type value:   C{str}
 
         @return: the value converted to its corresponding python type
-        @rtype:  depends on C{self.type} (DOCME)
+        @rtype:  depends on C{self.type}
 
         @raise ExifValueError: if the conversion fails
         """
@@ -257,7 +281,7 @@ class ExifTag(ListenerInterface):
         to pass to libexiv2.
 
         @param value: the value to be converted
-        @type value:  depends on C{self.type} (DOCME)
+        @type value:  depends on C{self.type}
 
         @return: the value converted to its corresponding string representation
         @rtype:  C{str}