dfsm: Add all the missing API reference comments
[bendy-bus:bendy-bus.git] / dfsm / dfsm-ast-statement.c
1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
2 /*
3  * D-Bus Simulator
4  * Copyright (C) Philip Withnall 2011 <philip@tecnocode.co.uk>
5  * 
6  * D-Bus Simulator is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * D-Bus Simulator is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with D-Bus Simulator.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 /**
21  * SECTION:dfsm-ast-statement
22  * @short_description: AST statement node
23  * @stability: Unstable
24  * @include: dfsm/dfsm-ast-statement.h
25  *
26  * Abstract AST node representing a single statement. Statements form the bodies of transitions, and change the state of the simulation or the bus.
27  */
28
29 #include <glib.h>
30
31 #include "dfsm-ast-statement.h"
32
33 G_DEFINE_ABSTRACT_TYPE (DfsmAstStatement, dfsm_ast_statement, DFSM_TYPE_AST_NODE)
34
35 static void
36 dfsm_ast_statement_class_init (DfsmAstStatementClass *klass)
37 {
38         /* Nothing to see here. */
39 }
40
41 static void
42 dfsm_ast_statement_init (DfsmAstStatement *self)
43 {
44         /* Nothing to see here. */
45 }
46
47 /**
48  * dfsm_ast_statement_execute:
49  * @self: a #DfsmAstStatement
50  * @environment: the environment to execute the statement in
51  * @output_sequence: an output sequence to append the effects of the statement to
52  *
53  * Execute a given state machine statement. This may modify the @environment.
54  *
55  * Any effects caused by execution of the statement will be appended (in execution order) to @output_sequence, which can later be evaluated by the
56  * caller. For example, all D-Bus signal emissions, method replies and error replies to D-Bus method calls are appended to @output_sequence in this
57  * manner.
58  *
59  * Return value: (transfer full): reply parameters from the statement, or %NULL
60  */
61 void
62 dfsm_ast_statement_execute (DfsmAstStatement *self, DfsmEnvironment *environment, DfsmOutputSequence *output_sequence)
63 {
64         DfsmAstStatementClass *klass;
65
66         g_return_if_fail (DFSM_IS_AST_STATEMENT (self));
67         g_return_if_fail (DFSM_IS_ENVIRONMENT (environment));
68
69         klass = DFSM_AST_STATEMENT_GET_CLASS (self);
70
71         g_assert (klass->execute != NULL);
72         klass->execute (self, environment, output_sequence);
73 }