Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

GeanyGenDoc: Update README.in, add HACKING

  • Loading branch information...
commit d3f965b8104fdfb55a81767aee69eb9fbfc346b5 1 parent 9e14964
Colomban Wendling b4n authored
2  geanygendoc/ChangeLog
@@ -9,6 +9,8 @@
9 9 probably the first new users would look at, then move it to the top.
10 10 * docs/manual.rst, docs/manual.html:
11 11 Add a small sentence in the introduction to guide the user in her read.
  12 + * README.in, HACKING:
  13 + Update README.in, add HACKING.
12 14
13 15
14 16 2010-06-14 Colomban Wendling <ban(at)herbesfolles(dot)org>
175 geanygendoc/HACKING
... ... @@ -0,0 +1,175 @@
  1 +======================
  2 +Hacking on GeanyGenDoc
  3 +======================
  4 +
  5 +.. contents::
  6 +
  7 +
  8 +Introduction
  9 +============
  10 +
  11 +This file contains some information that may be useful to start hacking on
  12 +GeanyGenDoc; but there might be some things that are missing. If you have a
  13 +question for which you can't find the answer, feel free to ask a developer
  14 +(me in fact, I'm currently the only one).
  15 +
  16 +
  17 +Directory structure
  18 +===================
  19 +
  20 +src/
  21 + Contains all the source code of GeanyGenDoc, see below for details.
  22 +
  23 +docs/
  24 + Contains the manual, this is the place to go to improve the end-user
  25 + documentation.
  26 +
  27 +data/
  28 + Contains the various data files of GeanyGenDoc.
  29 +
  30 + filetypes/
  31 + Contains the file type definitions. See the end-user documentation for
  32 + details on the syntax of these files.
  33 +
  34 +
  35 +Code organisation
  36 +=================
  37 +
  38 +All source files starts with the `ggd` prefix that, obviously, stands for
  39 +GeanyGenDoc.
  40 +
  41 +ggd-plugin.{c,h}
  42 + This is the actual plugin, the part that interacts with Geany directly:
  43 + it implements all the symbols that a Geany plusing must export; it takes care
  44 + of setting everything necessary up, and so on. Think of it as the plugin's
  45 + `main()`.
  46 +
  47 + This is the only part of the plugin that is allowed to export symbols (see
  48 + below).
  49 +
  50 +ggd.{c,h}
  51 + This is the higher-level API of the plugin. It is meant to be the primary API
  52 + to use to build and insert documentation basis on a Geany document.
  53 +
  54 +ggd-doc-setting.{c,h}, ggd-doc-type.{c,h}, ggd-file-type.{c,h}
  55 + The main three data types of GeanyGenDoc, and their manipulation functions
  56 +
  57 +ggd-file-type-loader.{c,h}
  58 + File type loader
  59 +
  60 +ggd-file-type-manager.{c,h}
  61 + High-level loading and management of file types, also acting as a cache
  62 +
  63 +ggd-options.{c,h}
  64 + Configuration manager
  65 +
  66 +ggd-tag-utils.{c,h}
  67 + Geany's tagmanager management and utility functions. Almost all acces to tags
  68 + is done through this module
  69 +
  70 +ggd-macros.h, ggd-utils.{c,h}
  71 + Various utility functions and macros
  72 +
  73 +ggd-widget-*
  74 + These files are custom GTK+ widgets used by the UI part of the plugin.
  75 +
  76 + ggd-widget-doctype-selector.{c,h}
  77 + The documentation type selector and manager widget
  78 +
  79 + ggd-widget-frame.{c,h}
  80 + A custom frame widget
  81 +
  82 +
  83 +Coding style
  84 +============
  85 +
  86 +The first rule is: look at the code and follow the style.
  87 +
  88 +To give further consideration, the style is close to 1TBS-K&R with some
  89 +GNU-style things. Here's an exemple, followed by notes about it:
  90 +
  91 +::
  92 +
  93 + /**
  94 + * a_function:
  95 + * @arg1: something
  96 + * @n: another thing
  97 + *
  98 + * This is the documentation of the function. Write documentation for each and
  99 + * every non-local function. Local function can has a full documentation but
  100 + * in a normal comment (starting with /* and not /**), or can either have only
  101 + * a few line describing it or no comment at all if it is enough explicit.
  102 + *
  103 + * Returns: A number, obviously... but what does it mean?
  104 + */
  105 + int
  106 + a_function (const char *arg1,
  107 + int n)
  108 + {
  109 + int a;
  110 + const char *b;
  111 +
  112 + a = foo ();
  113 + if (a == n) {
  114 + b = arg1;
  115 + } else {
  116 + int tmp;
  117 +
  118 + b = stuff (arg1, n, A_LONG_CONSTANT, ,
  119 + ANOTHER_LONG_CONSTANT_THAT_GOES_BEYOND_80TH_COLUMN);
  120 + if (got_it (&tmp)) {
  121 + a = tmp;
  122 + } else {
  123 + a = n;
  124 + }
  125 + }
  126 + if (! variable || (A_THIRD_WAY_TOO_LONG_CONSTANT && ITS_ME_AGAIN &&
  127 + PLEASE_STOP_THIS)) {
  128 + /* you may want to explain why you do this operation, so put a comment
  129 + * just before it. it is also good to document magic numbers such as this
  130 + * "8" that comes from nowhere. */
  131 + a = n << 8;
  132 + }
  133 +
  134 + return a;
  135 + }
  136 +
  137 +You can see that (in random order):
  138 +
  139 +* The indentation consists of 2 spaces per level -- no tabs;
  140 +* The return type is on its own line (as in GNU style);
  141 +* There is a space between function name and argumen list;
  142 +* Variables and arguments declarations are aligned, one per line.
  143 +* If the arguments of a function call, a macro, an expression, etc., would
  144 + overflow the 80th column rule, it is split on two (or more, as needed) lines,
  145 + aligned on the corresponding parenthesis;
  146 +* There is blank lines at two places: right after some variable declarations,
  147 + and right before the return statement;
  148 +* There is no parenthesis around the return statement;
  149 +* Put a space between the unary operator `!` and its operand;
  150 +* There is a space around binary operators;
  151 +* Use const everywhere it makes sense, almost like a sementic annotation;
  152 +* There is braces around every block (1TBS style);
  153 +* Constants are uppercase;
  154 +* So are macros that may have side effects;
  155 +* Decalre local variables at the scope they belongs;
  156 +* Document non-local functions with a Gtk-Doc documentation comment -- you know
  157 + what? GeanyGenDoc can help!
  158 +* You don't see it in this example, but give pointful names to functions,
  159 + variables, marcos, etc.
  160 +
  161 +
  162 +API, ABI, exported symbols, stuff like that
  163 +-------------------------------------------
  164 +
  165 +Always use static functions if they should have file scope; and prefix all
  166 +non-local symbol with the `ggd` prefix (with the appropriate case).
  167 +
  168 +Besides this, don't pollute the list of exported symbols of the plugin. Even if
  169 +all symbols that might be exported by accident are prefixed, exporting them has
  170 +no point (this isn't a library) and only bloates the output ELF (or whatever)
  171 +binary.
  172 +
  173 +To prevent this, all "public" (read: that is used outside its file/module)
  174 +should have a protorype that is protected with `GGD_BEGIN_PLUGIN_API`
  175 +and `GGD_END_PLUGIN_API` (see gdd-macros.h for details).
88 geanygendoc/README.in
... ... @@ -1,37 +1,93 @@
1   -General Information
2   -===================
  1 +===========
  2 +GeanyGenDoc
  3 +===========
  4 +
  5 +.. contents::
  6 +
  7 +
  8 +About
  9 +=====
  10 +
  11 +GeanyGenDoc is a plugin for Geany that aims to help code documentation by
  12 +automatically generating documentation comment basis from the source code.
3 13
4   -This is GeanyGenDoc @VERSION@, a plugin for Geany that aims to automatically
5   -generate documentation comment basis from the source code.
6 14
7 15 Requirements
8 16 ============
9 17
10 18 You will need the following packages to build GeanyGenDoc:
11   - - Geany >= 0.19 (http://www.geany.org/)
12   - - GTK+ >= 2.12 (http://www.gtk.org)
13   - - GLib >= 2.14 (http://www.gtk.org)
14   - - GIO >= 2.18 (http://www.gtk.org)
15   - - CTPL >= 0.2 (http://ctpl.tuxfamily.org/)
16   - - A working C compiler (GCC for example, http://gcc.gnu.org/)
17   - - A working make implementation (GNU make is recommended,
18   - http://www.gnu.org/software/make/)
  19 +
  20 +* Geany >= 0.19 (http://www.geany.org/)
  21 +* GTK+ >= 2.12 (http://www.gtk.org)
  22 +* GLib >= 2.14 (http://www.gtk.org)
  23 +* GIO >= 2.18 (http://www.gtk.org)
  24 +* CTPL >= 0.2 (http://ctpl.tuxfamily.org/)
  25 +* A working C compiler (GCC for example, http://gcc.gnu.org/)
  26 +* A working make implementation (GNU make is recommended,
  27 + http://www.gnu.org/software/make/)
19 28
20 29 You may also want the following packages that enables extra features:
21   - - Docutils (http://docutils.sourceforge.net/) -- or another implementation of
22   - rst2html -- is needed to (re)generate the HTML manual.
  30 +
  31 +* Docutils (http://docutils.sourceforge.net/) -- or another implementation of
  32 + rst2html -- is needed to (re)generate the HTML manual.
23 33
24 34
25 35 Installation
26 36 ============
27 37
28   -Compiling and installing the plugin is done by the following commands:
  38 +Compiling and installing the plugin is done by running the following
  39 +commands from the top-level directory (it is the parent of the one
  40 +containing this file if you're building GeanyGenDoc as part of Geany-plugins):
  41 +
  42 +::
29 43
30 44 $ ./configure
31 45 $ make
32 46 $ make install
33 47
34   -For more configuration details run
  48 +For more configuration details, run
  49 +
  50 +::
  51 +
35 52 $ ./configure --help
36 53
37 54 For detailed instructions, see the INSTALL file.
  55 +
  56 +
  57 +Usage
  58 +=====
  59 +
  60 +For more details about GeanyGenDoc, see the user manual that can be found in
  61 +the docs/ subirectory or opened with the menu item `Tools → Documentation
  62 +Generator → Open Manual` from the Geany window if you already runs GeanyGenDoc.
  63 +
  64 +
  65 +Hacking
  66 +=======
  67 +
  68 +See the HACKING file for information on how to get started on hacking
  69 +GeanyGenDoc internals.
  70 +
  71 +
  72 +License
  73 +=======
  74 +
  75 +GeanyGenDoc is distributed under the terms of the GNU General Public License
  76 +as published by the Free Software Foundation, either version 3 of the
  77 +License, or (at your option) any later version. You should have received a copy
  78 +of the GNU General Public License along with GeanyGenDoc. If not, see
  79 +<http://www.gnu.org/licenses/>.
  80 +
  81 +
  82 +Contact
  83 +=======
  84 +
  85 +You can mail me at <ban(at)herbesfolles(dot)org>, and I may also be on the
  86 +#geany channel on FreeNode, under the `b4n` nickname.
  87 +
  88 +
  89 +Bug reports and feature requests
  90 +--------------------------------
  91 +
  92 +To report a bug or ask for a new feature, please use the Geany-Plugins tracker
  93 +on SourceForge: http://sourceforge.net/tracker/?group_id=222729

0 comments on commit d3f965b

Please sign in to comment.
Something went wrong with that request. Please try again.