SF.net SVN: geany-plugins:[1514] trunk/geany-plugins/geanygendoc
colombanw at users.sourceforge.net
colombanw at xxxxx
Tue Aug 17 00:34:54 UTC 2010
Revision: 1514
http://geany-plugins.svn.sourceforge.net/geany-plugins/?rev=1514&view=rev
Author: colombanw
Date: 2010-08-17 00:34:54 +0000 (Tue, 17 Aug 2010)
Log Message:
-----------
GeanyGenDoc: Update README.in, add HACKING
Modified Paths:
--------------
trunk/geany-plugins/geanygendoc/ChangeLog
trunk/geany-plugins/geanygendoc/README.in
Added Paths:
-----------
trunk/geany-plugins/geanygendoc/HACKING
Modified: trunk/geany-plugins/geanygendoc/ChangeLog
===================================================================
--- trunk/geany-plugins/geanygendoc/ChangeLog 2010-08-17 00:34:33 UTC (rev 1513)
+++ trunk/geany-plugins/geanygendoc/ChangeLog 2010-08-17 00:34:54 UTC (rev 1514)
@@ -9,6 +9,8 @@
probably the first new users would look at, then move it to the top.
* docs/manual.rst, docs/manual.html:
Add a small sentence in the introduction to guide the user in her read.
+ * README.in, HACKING:
+ Update README.in, add HACKING.
2010-06-14 Colomban Wendling <ban(at)herbesfolles(dot)org>
Added: trunk/geany-plugins/geanygendoc/HACKING
===================================================================
--- trunk/geany-plugins/geanygendoc/HACKING (rev 0)
+++ trunk/geany-plugins/geanygendoc/HACKING 2010-08-17 00:34:54 UTC (rev 1514)
@@ -0,0 +1,175 @@
+======================
+Hacking on GeanyGenDoc
+======================
+
+.. contents::
+
+
+Introduction
+============
+
+This file contains some information that may be useful to start hacking on
+GeanyGenDoc; but there might be some things that are missing. If you have a
+question for which you can't find the answer, feel free to ask a developer
+(me in fact, I'm currently the only one).
+
+
+Directory structure
+===================
+
+src/
+ Contains all the source code of GeanyGenDoc, see below for details.
+
+docs/
+ Contains the manual, this is the place to go to improve the end-user
+ documentation.
+
+data/
+ Contains the various data files of GeanyGenDoc.
+
+ filetypes/
+ Contains the file type definitions. See the end-user documentation for
+ details on the syntax of these files.
+
+
+Code organisation
+=================
+
+All source files starts with the `ggd` prefix that, obviously, stands for
+GeanyGenDoc.
+
+ggd-plugin.{c,h}
+ This is the actual plugin, the part that interacts with Geany directly:
+ it implements all the symbols that a Geany plusing must export; it takes care
+ of setting everything necessary up, and so on. Think of it as the plugin's
+ `main()`.
+
+ This is the only part of the plugin that is allowed to export symbols (see
+ below).
+
+ggd.{c,h}
+ This is the higher-level API of the plugin. It is meant to be the primary API
+ to use to build and insert documentation basis on a Geany document.
+
+ggd-doc-setting.{c,h}, ggd-doc-type.{c,h}, ggd-file-type.{c,h}
+ The main three data types of GeanyGenDoc, and their manipulation functions
+
+ggd-file-type-loader.{c,h}
+ File type loader
+
+ggd-file-type-manager.{c,h}
+ High-level loading and management of file types, also acting as a cache
+
+ggd-options.{c,h}
+ Configuration manager
+
+ggd-tag-utils.{c,h}
+ Geany's tagmanager management and utility functions. Almost all acces to tags
+ is done through this module
+
+ggd-macros.h, ggd-utils.{c,h}
+ Various utility functions and macros
+
+ggd-widget-*
+ These files are custom GTK+ widgets used by the UI part of the plugin.
+
+ ggd-widget-doctype-selector.{c,h}
+ The documentation type selector and manager widget
+
+ ggd-widget-frame.{c,h}
+ A custom frame widget
+
+
+Coding style
+============
+
+The first rule is: look at the code and follow the style.
+
+To give further consideration, the style is close to 1TBS-K&R with some
+GNU-style things. Here's an exemple, followed by notes about it:
+
+::
+
+ /**
+ * a_function:
+ * @arg1: something
+ * @n: another thing
+ *
+ * This is the documentation of the function. Write documentation for each and
+ * every non-local function. Local function can has a full documentation but
+ * in a normal comment (starting with /* and not /**), or can either have only
+ * a few line describing it or no comment at all if it is enough explicit.
+ *
+ * Returns: A number, obviously... but what does it mean?
+ */
+ int
+ a_function (const char *arg1,
+ int n)
+ {
+ int a;
+ const char *b;
+
+ a = foo ();
+ if (a == n) {
+ b = arg1;
+ } else {
+ int tmp;
+
+ b = stuff (arg1, n, A_LONG_CONSTANT, ,
+ ANOTHER_LONG_CONSTANT_THAT_GOES_BEYOND_80TH_COLUMN);
+ if (got_it (&tmp)) {
+ a = tmp;
+ } else {
+ a = n;
+ }
+ }
+ if (! variable || (A_THIRD_WAY_TOO_LONG_CONSTANT && ITS_ME_AGAIN &&
+ PLEASE_STOP_THIS)) {
+ /* you may want to explain why you do this operation, so put a comment
+ * just before it. it is also good to document magic numbers such as this
+ * "8" that comes from nowhere. */
+ a = n << 8;
+ }
+
+ return a;
+ }
+
+You can see that (in random order):
+
+* The indentation consists of 2 spaces per level -- no tabs;
+* The return type is on its own line (as in GNU style);
+* There is a space between function name and argumen list;
+* Variables and arguments declarations are aligned, one per line.
+* If the arguments of a function call, a macro, an expression, etc., would
+ overflow the 80th column rule, it is split on two (or more, as needed) lines,
+ aligned on the corresponding parenthesis;
+* There is blank lines at two places: right after some variable declarations,
+ and right before the return statement;
+* There is no parenthesis around the return statement;
+* Put a space between the unary operator `!` and its operand;
+* There is a space around binary operators;
+* Use const everywhere it makes sense, almost like a sementic annotation;
+* There is braces around every block (1TBS style);
+* Constants are uppercase;
+* So are macros that may have side effects;
+* Decalre local variables at the scope they belongs;
+* Document non-local functions with a Gtk-Doc documentation comment -- you know
+ what? GeanyGenDoc can help!
+* You don't see it in this example, but give pointful names to functions,
+ variables, marcos, etc.
+
+
+API, ABI, exported symbols, stuff like that
+-------------------------------------------
+
+Always use static functions if they should have file scope; and prefix all
+non-local symbol with the `ggd` prefix (with the appropriate case).
+
+Besides this, don't pollute the list of exported symbols of the plugin. Even if
+all symbols that might be exported by accident are prefixed, exporting them has
+no point (this isn't a library) and only bloates the output ELF (or whatever)
+binary.
+
+To prevent this, all "public" (read: that is used outside its file/module)
+should have a protorype that is protected with `GGD_BEGIN_PLUGIN_API`
+and `GGD_END_PLUGIN_API` (see gdd-macros.h for details).
Modified: trunk/geany-plugins/geanygendoc/README.in
===================================================================
--- trunk/geany-plugins/geanygendoc/README.in 2010-08-17 00:34:33 UTC (rev 1513)
+++ trunk/geany-plugins/geanygendoc/README.in 2010-08-17 00:34:54 UTC (rev 1514)
@@ -1,37 +1,93 @@
-General Information
-===================
+===========
+GeanyGenDoc
+===========
-This is GeanyGenDoc @VERSION@, a plugin for Geany that aims to automatically
-generate documentation comment basis from the source code.
+.. contents::
+
+About
+=====
+
+GeanyGenDoc is a plugin for Geany that aims to help code documentation by
+automatically generating documentation comment basis from the source code.
+
+
Requirements
============
You will need the following packages to build GeanyGenDoc:
- - Geany >= 0.19 (http://www.geany.org/)
- - GTK+ >= 2.12 (http://www.gtk.org)
- - GLib >= 2.14 (http://www.gtk.org)
- - GIO >= 2.18 (http://www.gtk.org)
- - CTPL >= 0.2 (http://ctpl.tuxfamily.org/)
- - A working C compiler (GCC for example, http://gcc.gnu.org/)
- - A working make implementation (GNU make is recommended,
- http://www.gnu.org/software/make/)
+* Geany >= 0.19 (http://www.geany.org/)
+* GTK+ >= 2.12 (http://www.gtk.org)
+* GLib >= 2.14 (http://www.gtk.org)
+* GIO >= 2.18 (http://www.gtk.org)
+* CTPL >= 0.2 (http://ctpl.tuxfamily.org/)
+* A working C compiler (GCC for example, http://gcc.gnu.org/)
+* A working make implementation (GNU make is recommended,
+ http://www.gnu.org/software/make/)
+
You may also want the following packages that enables extra features:
- - Docutils (http://docutils.sourceforge.net/) -- or another implementation of
- rst2html -- is needed to (re)generate the HTML manual.
+* Docutils (http://docutils.sourceforge.net/) -- or another implementation of
+ rst2html -- is needed to (re)generate the HTML manual.
+
Installation
============
-Compiling and installing the plugin is done by the following commands:
+Compiling and installing the plugin is done by running the following
+commands from the top-level directory (it is the parent of the one
+containing this file if you're building GeanyGenDoc as part of Geany-plugins):
+::
+
$ ./configure
$ make
$ make install
-For more configuration details run
+For more configuration details, run
+
+::
+
$ ./configure --help
For detailed instructions, see the INSTALL file.
+
+
+Usage
+=====
+
+For more details about GeanyGenDoc, see the user manual that can be found in
+the docs/ subirectory or opened with the menu item `Tools → Documentation
+Generator → Open Manual` from the Geany window if you already runs GeanyGenDoc.
+
+
+Hacking
+=======
+
+See the HACKING file for information on how to get started on hacking
+GeanyGenDoc internals.
+
+
+License
+=======
+
+GeanyGenDoc is distributed under the terms of the GNU General Public License
+as published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version. You should have received a copy
+of the GNU General Public License along with GeanyGenDoc. If not, see
+<http://www.gnu.org/licenses/>.
+
+
+Contact
+=======
+
+You can mail me at <ban(at)herbesfolles(dot)org>, and I may also be on the
+#geany channel on FreeNode, under the `b4n` nickname.
+
+
+Bug reports and feature requests
+--------------------------------
+
+To report a bug or ask for a new feature, please use the Geany-Plugins tracker
+on SourceForge: http://sourceforge.net/tracker/?group_id=222729
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the Plugins-Commits
mailing list