From 15ed404279b72eeaa2561776a3f674737022ef04 Mon Sep 17 00:00:00 2001 From: Jim Nelson Date: Thu, 25 Apr 2013 20:03:42 -0700 Subject: [PATCH] Produce Valadoc for the Engine: Closes #4346 "make valadoc" will now produce valadoc/ in the top-level directory. Still a lot of work to do to clean this up, as some names need to be fixed for better heirarchy and others should be made private to prevent leakage. And, of course, more classes, namespaces, and methods need to be properly documented. --- .gitignore | 1 + Makefile.in | 4 ++ cmake/FindValadoc.cmake | 20 ++++++++++ src/CMakeLists.txt | 15 +++++++ src/engine/api/geary-folder.vala | 7 ++-- src/engine/db/db-connection.vala | 40 +++++++++---------- src/engine/db/db.vala | 8 ++-- src/engine/imap/message/imap-parameter.vala | 4 +- .../rfc822-gmime-filter-blockquotes.vala | 2 +- .../rfc822/rfc822-gmime-filter-flowed.vala | 2 +- .../rfc822/rfc822-gmime-filter-plain.vala | 2 +- src/engine/rfc822/rfc822-message.vala | 6 +-- src/engine/util/util-stream.vala | 2 +- 13 files changed, 77 insertions(+), 36 deletions(-) create mode 100644 cmake/FindValadoc.cmake diff --git a/.gitignore b/.gitignore index d6fc41b9..444284bf 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ build/ *.xz *.swp bindings/vapi/gmime-2.6/gmime-2.6.gi +/valadoc diff --git a/Makefile.in b/Makefile.in index 3285ae2e..814cbfc5 100644 --- a/Makefile.in +++ b/Makefile.in @@ -46,3 +46,7 @@ dist: ubuntu: @$(MAKE) -C $(BUILD_DIR) ubuntu +.PHONY: valadoc +valadoc: + @$(MAKE) -C $(BUILD_DIR) valadoc + diff --git a/cmake/FindValadoc.cmake b/cmake/FindValadoc.cmake new file mode 100644 index 00000000..2fc0c736 --- /dev/null +++ b/cmake/FindValadoc.cmake @@ -0,0 +1,20 @@ + +# Search for the valadocc executable in the usual system paths. +find_program(VALADOC_EXECUTABLE NAMES valadoc) + +# Handle the QUIETLY and REQUIRED arguments, which may be given to the find call. +# Furthermore set VALA_FOUND to TRUE if Vala has been found (aka. +# VALA_EXECUTABLE is set) + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Valadoc DEFAULT_MSG VALADOC_EXECUTABLE) + +mark_as_advanced(VALADOC_EXECUTABLE) + +# Determine the valac version +if(VALA_FOUND) + execute_process(COMMAND ${VALA_EXECUTABLE} "--version" + OUTPUT_VARIABLE "VALA_VERSION") + string(REPLACE "Vala" "" "VALA_VERSION" ${VALA_VERSION}) + string(STRIP ${VALA_VERSION} "VALA_VERSION") +endif(VALA_FOUND) diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 735298c3..d1c940b4 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -546,6 +546,21 @@ add_custom_command( ${CMAKE_COMMAND} -E copy gearyd ${CMAKE_BINARY_DIR}/ ) +# Valadoc +################################################# +foreach(pkg ${ENGINE_PACKAGES}) + list(APPEND valadoc_pkg_opts "--pkg=${pkg}") +endforeach(pkg ${ENGINE_PACKAGES}) + +include(FindValadoc) +add_custom_target( + valadoc + WORKING_DIRECTORY + ${CMAKE_SOURCE_DIR}/src + COMMAND + ${VALADOC_EXECUTABLE} --force --no-protected -b ${CMAKE_CURRENT_SOURCE_DIR} -o ${CMAKE_SOURCE_DIR}/valadoc --package-name=geary --package-version=${VERSION} ${ENGINE_SRC} ${valadoc_pkg_opts} --vapidir=${CMAKE_SOURCE_DIR}/bindings/vapi +) + ## Make clean: remove copied files ################################################## set_property( diff --git a/src/engine/api/geary-folder.vala b/src/engine/api/geary-folder.vala index 9fc3828a..f3ac6c4a 100644 --- a/src/engine/api/geary-folder.vala +++ b/src/engine/api/geary-folder.vala @@ -51,9 +51,10 @@ public interface Geary.Folder : BaseObject { /** * Flags used for retrieving email. - * LOCAL_ONLY: fetch from the local store only - * FORCE_UPDATE: fetch from remote only (results merged into local store) - * EXCLUDING_ID: exclude the provided ID + * + * * LOCAL_ONLY: fetch from the local store only + * * FORCE_UPDATE: fetch from remote only (results merged into local store) + * * EXCLUDING_ID: exclude the provided ID */ [Flags] public enum ListFlags { diff --git a/src/engine/db/db-connection.vala b/src/engine/db/db-connection.vala index 75267869..aac0df98 100644 --- a/src/engine/db/db-connection.vala +++ b/src/engine/db/db-connection.vala @@ -38,21 +38,21 @@ public class Geary.Db.Connection : Geary.Db.Context { private static int next_cx_number = 0; /** - * See http://www.sqlite.org/c3ref/last_insert_rowid.html + * See [[http://www.sqlite.org/c3ref/last_insert_rowid.html]] */ public int64 last_insert_rowid { get { return db.last_insert_rowid(); } } /** - * See http://www.sqlite.org/c3ref/changes.html + * See [[http://www.sqlite.org/c3ref/changes.html]] */ public int last_modified_rows { get { return db.changes(); } } /** - * See http://www.sqlite.org/c3ref/total_changes.html + * See [[http://www.sqlite.org/c3ref/total_changes.html]] */ public int total_modified_rows { get { return db.total_changes(); @@ -88,14 +88,14 @@ public class Geary.Db.Connection : Geary.Db.Context { /** * Execute a plain text SQL statement. More than one SQL statement may be in the string. See - * http://www.sqlite.org/lang.html for more information on SQLite's SQL syntax. + * [[http://www.sqlite.org/lang.html]] for more information on SQLite's SQL syntax. * * There is no way to retrieve a result iterator from this call. * * This may be called from a TransactionMethod called within exec_transaction() or * Db.Database.exec_transaction_async(). * - * See http://www.sqlite.org/c3ref/exec.html + * See [[http://www.sqlite.org/c3ref/exec.html]] */ public void exec(string sql, Cancellable? cancellable = null) throws Error { check_cancelled("Connection.exec", cancellable); @@ -133,7 +133,7 @@ public class Geary.Db.Connection : Geary.Db.Context { /** * Prepares a Statement which may have values bound to it and executed. See - * http://www.sqlite.org/c3ref/prepare.html + * [[http://www.sqlite.org/c3ref/prepare.html]] */ public Statement prepare(string sql) throws DatabaseError { return new Statement(this, sql); @@ -164,7 +164,7 @@ public class Geary.Db.Connection : Geary.Db.Context { } /** - * Returns the result of a PRAGMA as a boolean. See http://www.sqlite.org/pragma.html. + * Returns the result of a PRAGMA as a boolean. See [[http://www.sqlite.org/pragma.html]] * * Note that if the PRAGMA does not return a boolean, the results are undefined. A boolean * in SQLite, however, includes 1 and 0, so an integer may be mistaken as a boolean. @@ -200,7 +200,7 @@ public class Geary.Db.Connection : Geary.Db.Context { } /** - * Returns the result of a PRAGMA as an integer. See http://www.sqlite.org/pragma.html + * Returns the result of a PRAGMA as an integer. See [[http://www.sqlite.org/pragma.html]] * * Note that if the PRAGMA does not return an integer, the results are undefined. Since a * boolean in SQLite includes 1 and 0, it's possible for those values to be converted to an @@ -218,7 +218,7 @@ public class Geary.Db.Connection : Geary.Db.Context { } /** - * Returns the result of a PRAGMA as a string. See http://www.sqlite.org/pragma.html + * Returns the result of a PRAGMA as a string. See [[http://www.sqlite.org/pragma.html]] */ public string get_pragma_string(string name) throws Error { return query("PRAGMA %s".printf(name)).string_at(0); @@ -242,7 +242,7 @@ public class Geary.Db.Connection : Geary.Db.Context { * Sets the user version number, which is a private number maintained by the user. * VersionedDatabase uses this to maintain the version number of the database. * - * See http://www.sqlite.org/pragma.html#pragma_schema_version + * See [[http://www.sqlite.org/pragma.html#pragma_schema_version]] */ public void set_user_version_number(int version) throws Error { set_pragma_int(PRAGMA_USER_VERSION, version); @@ -250,7 +250,7 @@ public class Geary.Db.Connection : Geary.Db.Context { /** * Gets the schema version number, which is maintained by SQLite. See - * http://www.sqlite.org/pragma.html#pragma_schema_version + * [[http://www.sqlite.org/pragma.html#pragma_schema_version]] * * Since this number is maintained by SQLite, Geary.Db doesn't offer a way to set it. */ @@ -259,56 +259,56 @@ public class Geary.Db.Connection : Geary.Db.Context { } /** - * See http://www.sqlite.org/pragma.html#pragma_foreign_keys + * See [[http://www.sqlite.org/pragma.html#pragma_foreign_keys]] */ public void set_foreign_keys(bool enabled) throws Error { set_pragma_bool(PRAGMA_FOREIGN_KEYS, enabled); } /** - * See http://www.sqlite.org/pragma.html#pragma_foreign_keys + * See [[http://www.sqlite.org/pragma.html#pragma_foreign_keys]] */ public bool get_foreign_keys() throws Error { return get_pragma_bool(PRAGMA_FOREIGN_KEYS); } /** - * See http://www.sqlite.org/pragma.html#pragma_recursive_triggers + * See [[http://www.sqlite.org/pragma.html#pragma_recursive_triggers]] */ public void set_recursive_triggers(bool enabled) throws Error { set_pragma_bool(PRAGMA_RECURSIVE_TRIGGERS, enabled); } /** - * See http://www.sqlite.org/pragma.html#pragma_recursive_triggers + * See [[http://www.sqlite.org/pragma.html#pragma_recursive_triggers]] */ public bool get_recursive_triggers() throws Error { return get_pragma_bool(PRAGMA_RECURSIVE_TRIGGERS); } /** - * See http://www.sqlite.org/pragma.html#pragma_secure_delete + * See [[http://www.sqlite.org/pragma.html#pragma_secure_delete]] */ public void set_secure_delete(bool enabled) throws Error { set_pragma_bool(PRAGMA_SECURE_DELETE, enabled); } /** - * See http://www.sqlite.org/pragma.html#pragma_secure_delete + * See [[http://www.sqlite.org/pragma.html#pragma_secure_delete]] */ public bool get_secure_delete() throws Error { return get_pragma_bool(PRAGMA_SECURE_DELETE); } /** - * See http://www.sqlite.org/pragma.html#pragma_synchronous + * See [[http://www.sqlite.org/pragma.html#pragma_synchronous]] */ public void set_synchronous(SynchronousMode mode) throws Error { set_pragma_string(PRAGMA_SYNCHRONOUS, mode.sql()); } /** - * See http://www.sqlite.org/pragma.html#pragma_synchronous + * See [[http://www.sqlite.org/pragma.html#pragma_synchronous]] */ public SynchronousMode get_synchronous() throws Error { return SynchronousMode.parse(get_pragma_string(PRAGMA_SYNCHRONOUS)); @@ -326,7 +326,7 @@ public class Geary.Db.Connection : Geary.Db.Context { * It's inadvisable to call exec_transaction() inside exec_transaction(). SQLite has a notion * of savepoints that allow for nested transactions; they are not currently supported. * - * See http://www.sqlite.org/lang_transaction.html + * See [[http://www.sqlite.org/lang_transaction.html]] */ public TransactionOutcome exec_transaction(TransactionType type, TransactionMethod cb, Cancellable? cancellable = null) throws Error { diff --git a/src/engine/db/db.vala b/src/engine/db/db.vala index e67898f7..e8a6b3c6 100644 --- a/src/engine/db/db.vala +++ b/src/engine/db/db.vala @@ -57,28 +57,28 @@ public delegate TransactionOutcome TransactionMethod(Connection cx, Cancellable? private delegate int SqliteExecOperation(); /** - * See http://www.sqlite.org/c3ref/threadsafe.html + * See [[http://www.sqlite.org/c3ref/threadsafe.html]] */ public bool threadsafe() { return Sqlite.threadsafe() != 0; } /** - * See http://www.sqlite.org/c3ref/libversion.html + * See [[http://www.sqlite.org/c3ref/libversion.html]] */ public unowned string sqlite_version() { return Sqlite.libversion(); } /** - * See http://www.sqlite.org/c3ref/libversion.html + * See [[http://www.sqlite.org/c3ref/libversion.html]] */ public int sqlite_version_number() { return Sqlite.libversion_number(); } /** - * See http://www.sqlite.org/c3ref/enable_shared_cache.html + * See [[http://www.sqlite.org/c3ref/enable_shared_cache.html]] */ public bool set_shared_cache_mode(bool enabled) { return sqlite3_enable_shared_cache(enabled ? 1 : 0) == Sqlite.OK; diff --git a/src/engine/imap/message/imap-parameter.vala b/src/engine/imap/message/imap-parameter.vala index dbe62cbd..64625f3c 100644 --- a/src/engine/imap/message/imap-parameter.vala +++ b/src/engine/imap/message/imap-parameter.vala @@ -190,7 +190,7 @@ public class Geary.Imap.ListParameter : Geary.Imap.Parameter { * * TODO: This call can cause memory leaks when used with the "as" operator until the following * Vala bug is fixed (probably in version 0.19.1). - * https://bugzilla.gnome.org/show_bug.cgi?id=695671 + * [[https://bugzilla.gnome.org/show_bug.cgi?id=695671]] */ public new Parameter? get(int index) { return ((index >= 0) && (index < list.size)) ? list.get(index) : null; @@ -202,7 +202,7 @@ public class Geary.Imap.ListParameter : Geary.Imap.Parameter { * * TODO: This call can cause memory leaks when used with the "as" operator until the following * Vala bug is fixed (probably in version 0.19.1). - * https://bugzilla.gnome.org/show_bug.cgi?id=695671 + * [[https://bugzilla.gnome.org/show_bug.cgi?id=695671]] */ public Parameter get_required(int index) throws ImapError { if ((index < 0) || (index >= list.size)) diff --git a/src/engine/rfc822/rfc822-gmime-filter-blockquotes.vala b/src/engine/rfc822/rfc822-gmime-filter-blockquotes.vala index 11bea5c9..2e01cdcb 100644 --- a/src/engine/rfc822/rfc822-gmime-filter-blockquotes.vala +++ b/src/engine/rfc822/rfc822-gmime-filter-blockquotes.vala @@ -6,7 +6,7 @@ // Filter to insert blockquotes, put a div around the signature marker, and wrap the whole thing // in a styled div. -class GMime.FilterBlockquotes : GMime.Filter { +private class Geary.RFC822.FilterBlockquotes : GMime.Filter { // Invariant: True iff we are either at the beginning of a line, or all characters seen so far // have been quote markers or part of a tag. private bool in_prefix; diff --git a/src/engine/rfc822/rfc822-gmime-filter-flowed.vala b/src/engine/rfc822/rfc822-gmime-filter-flowed.vala index 779b7ba5..b0c877b0 100644 --- a/src/engine/rfc822/rfc822-gmime-filter-flowed.vala +++ b/src/engine/rfc822/rfc822-gmime-filter-flowed.vala @@ -5,7 +5,7 @@ */ // Filter to correctly handle flowed text as described in RFC 2646. -class GMime.FilterFlowed : GMime.Filter { +private class Geary.RFC822.FilterFlowed : GMime.Filter { private char quote_marker; private bool delsp; diff --git a/src/engine/rfc822/rfc822-gmime-filter-plain.vala b/src/engine/rfc822/rfc822-gmime-filter-plain.vala index a6c5c4bd..c6d0bf90 100644 --- a/src/engine/rfc822/rfc822-gmime-filter-plain.vala +++ b/src/engine/rfc822/rfc822-gmime-filter-plain.vala @@ -5,7 +5,7 @@ */ // Filter to mark quoted text in plain (non-flowed) text -class GMime.FilterPlain : GMime.Filter { +private class Geary.RFC822.FilterPlain : GMime.Filter { // Invariant: True iff we are either at the beginning of a line, or all characters seen so far // have been quote markers. private bool in_prefix; diff --git a/src/engine/rfc822/rfc822-message.vala b/src/engine/rfc822/rfc822-message.vala index cda44e4b..7b42702f 100644 --- a/src/engine/rfc822/rfc822-message.vala +++ b/src/engine/rfc822/rfc822-message.vala @@ -551,14 +551,14 @@ public class Geary.RFC822.Message : BaseObject { string delsp_par = part.get_content_type_parameter("DelSp") ?? "no"; bool delsp = (delsp_par.down() == "yes"); if (flowed) - stream_filter.add(new GMime.FilterFlowed(to_html, delsp)); + stream_filter.add(new Geary.RFC822.FilterFlowed(to_html, delsp)); if (to_html) { if (!flowed) - stream_filter.add(new GMime.FilterPlain()); + stream_filter.add(new Geary.RFC822.FilterPlain()); // HTML filter does stupid stuff to \r, so get rid of them. stream_filter.add(new GMime.FilterCRLF(false, false)); stream_filter.add(new GMime.FilterHTML(GMime.FILTER_HTML_CONVERT_URLS, 0)); - stream_filter.add(new GMime.FilterBlockquotes()); + stream_filter.add(new Geary.RFC822.FilterBlockquotes()); } wrapper.write_to_stream(stream_filter); diff --git a/src/engine/util/util-stream.vala b/src/engine/util/util-stream.vala index 5b9aa7e7..a9ae514a 100644 --- a/src/engine/util/util-stream.vala +++ b/src/engine/util/util-stream.vala @@ -4,7 +4,7 @@ * (version 2.1 or later). See the COPYING file in this distribution. */ -namespace Stream { +namespace Geary.Stream { public async void write_all_async(OutputStream outs, uint8[] data, ssize_t offset = 0, int length = -1, int priority = GLib.Priority.DEFAULT, Cancellable? cancellable = null) throws Error {