diff options
author | Kjell Ahlstedt <kjell.ahlstedt@bredband.net> | 2013-11-13 10:33:22 +0100 |
---|---|---|
committer | Kjell Ahlstedt <kjell.ahlstedt@bredband.net> | 2013-11-13 10:33:22 +0100 |
commit | 3611c97651e645d87d6bf06e1d0c66f0c6fdce10 (patch) | |
tree | 0112538e1b11f006867ab08e192c2626c5b4c4eb | |
parent | 1b9b3ee7f9b9b1ffced2c871b95ca867af1f8243 (diff) | |
download | glibmm-3611c97651e645d87d6bf06e1d0c66f0c6fdce10.tar.gz |
Gio::content_type_*(): Improve documentation
* gio/giomm/contenttype.h: Add @defgroup giommContentType. Useful as
a link target from Gtk::AppChooser, similar to a link from
GtkAppChooser:content-type to GContentType. See gtk+ bug #650012.
Several minor fixes in content_type_*() docs.
-rw-r--r-- | gio/giomm/contenttype.h | 36 |
1 files changed, 25 insertions, 11 deletions
diff --git a/gio/giomm/contenttype.h b/gio/giomm/contenttype.h index af27f24f..ee142644 100644 --- a/gio/giomm/contenttype.h +++ b/gio/giomm/contenttype.h @@ -27,6 +27,15 @@ namespace Gio { +/** @defgroup giommContentType Platform-specific content typing + * A content type is a platform specific string that defines the type of a file. + * On UNIX it is a <a href="http://www.wikipedia.org/wiki/Internet_media_type">mime type</a> + * like "text/plain" or "image/png". + * On Win32 it is an extension string like ".doc", ".txt" or a perceived + * string like "audio". Such strings can be looked up in the registry at + * HKEY_CLASSES_ROOT. + * @{ + */ /** * Compares two content types for equality. @@ -43,7 +52,7 @@ bool content_type_equals(const Glib::ustring& type1, * Determines if @a type is a subset of @a supertype. * * @param type A content type string. - * @param supertype A string. + * @param supertype A content type string. * * @return true if @a type is a kind of @a supertype, false otherwise. */ @@ -71,19 +80,19 @@ bool content_type_is_unknown(const Glib::ustring& type); Glib::ustring content_type_get_description(const Glib::ustring& type); /** - * Gets the mime-type for the content type. If one is registered + * Gets the mime-type for the content type, if one is registered. * * @param type A content type string. * - * @return the registered mime-type for the given @a type, or NULL if unknown. + * @return the registered mime-type for the given @a type, or an empty string if unknown. */ Glib::ustring content_type_get_mime_type(const Glib::ustring& type); /** - * @param type A content type string. - * * Gets the icon for a content type. * + * @param type A content type string. + * * @return Icon corresponding to the content type. */ Glib::RefPtr<Icon> content_type_get_icon(const Glib::ustring& type); @@ -92,7 +101,7 @@ Glib::RefPtr<Icon> content_type_get_icon(const Glib::ustring& type); * Gets the symbolic icon for a content type. * * @param type A content type string. - * @return Icon corresponding to the content type. + * @return symbolic Icon corresponding to the content type. * * @newin{2,34} */ @@ -120,12 +129,14 @@ Glib::ustring content_type_from_mime_type(const Glib::ustring& mime_type); /** * Guesses the content type based on example data. If the function is uncertain, - * @a result_uncertain will be set to true + * @a result_uncertain will be set to true. Either @a filename may be an empty + * string or @a data may be <tt>0</tt>, in which case the guess will be based + * solely on the other argument. * * @param filename a string. * @param data A stream of data. * @param data_size The size of @a data. - * @param result_uncertain A flag indicating the certainty of the result. + * @param[out] result_uncertain A flag indicating the certainty of the result. * @return A string indicating a guessed content type for the * given data. */ @@ -135,11 +146,12 @@ Glib::ustring content_type_guess(const std::string& filename, /** * Guesses the content type based on example data. If the function is uncertain, - * @a result_uncertain will be set to true + * @a result_uncertain will be set to true. @a filename may be an empty string, + * in which case the guess will be based solely on @a data. * * @param filename a string. * @param data A stream of data. - * @param result_uncertain A flag indicating the certainty of the result. + * @param[out] result_uncertain A flag indicating the certainty of the result. * @return A string indicating a guessed content type for the * given data. */ @@ -153,7 +165,7 @@ Glib::ustring content_type_guess(const std::string& filename, * * The types returned all have the form x-content/foo, e.g. * x-content/audio-cdda (for audio CDs) or x-content/image-dcf - * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * (for a camera memory card). See the <a href="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</a> * specification for more on x-content types. * * @param root The root of the tree to guess a type for. @@ -171,5 +183,7 @@ Glib::StringArrayHandle content_type_guess_for_tree(const Glib::RefPtr<const Fil */ Glib::ListHandle<Glib::ustring> content_types_get_registered(); +/** @} group giommContentType */ + } // namespace Gio #endif // _GIOMM_CONTENTTYPE_H |