Revision: 1514 http://geany-plugins.svn.sourceforge.net/geany-plugins/?rev=1514&view=re... 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.