Hi
I opened CR #19 in the hope that we agree on some formatting and documentation
rules ( http://www.openvas.org/openvas-cr-19.html ).
As I see it, there are no alternatives to doxygen. If we agree on doxygen we
further have to agree on a doxygen configuration file (as long as
documentation is local -> trivial) and on a style for the documentation
blocks itself, as there are several possibilities (
http://www.stack.nl/~dimitri/doxygen/docblocks.html ).
I opt for the javadoc-like style ( e.g. @param ).
Note that I myself will not participate in huge discussions about where to put
a space, a bracket, a newline etc, as the main aim is that we 1) agree on one
style and 2) gradually bring a consistent look into the OpenVAS code base and
3) achieve professional documentation.
That means, I will agree to everybody with a strong opinion.
Attached is a first proposal for an example file. It is based on
slad_install.c and not intended to be compiled.
I would like to open the voting quite soon (I vote +1).
Felix
--
Felix Wolfsteller | ++49-541-335 08 3451 | http://www.intevation.de/
PGP Key: 39DE0100
Intevation GmbH, Neuer Graben 17, 49074 Osnabrück | AG Osnabrück, HR B 18998
Geschäftsführer: Frank Koormann, Bernhard Reiter, Dr. Jan-Oliver Wagner
/* OpenVAS-Client
* $Id$
* Description: Proposed formating example (altered slad_install.c)
*
* Authors:
* Felix Wolfsteller <[EMAIL PROTECTED]>
*
* Copyright:
* Copyright (C) 2008 by Intevation GmbH
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2,
* or, at your option, any later version as published by the Free
* Software Foundation
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* In addition, as a special exception, you have
* permission to link the code of this program with the OpenSSL
* library (or with modified versions of OpenSSL that use the same
* license as OpenSSL), and distribute linked combinations including
* the two. You must obey the GNU General Public License in all
* respects for all of the code used other than OpenSSL. If you
* modify this file, you may extend this exception to your version
* of the file, but you are not obligated to do so. If you do not
* wish to do so, delete this exception statement from your version.
*/
#include <unistd.h>
#include <gtk/gtk.h>
#include <sys/types.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "nessus_i18n.h"
#include "module.h"
/**
* Defines follow the includes which follow the header, are capitalized and can
* be documented.\n
* Documentation is done in the source file, not the header file.
*/
#define SOMEDEFINE "fine"
/**
* Static functions do not neccessarily begin with the module name.
* @param str Parameters can be described like this.
*/
static void statfunc(gchar *str)
{
/* Indentation by 2 blanks, single lines should not exceed 80 chars */
GtkWidget* m = gtk_message_dialog_new(GTK_WINDOW(NULL),
( GTK_DIALOG_MODAL
| GTK_DIALOG_DESTROY_WITH_PARENT),
GTK_MESSAGE_ERROR, GTK_BUTTONS_OK, str);
/* (If 80 chars per line do not suffice, try to break it up nicely) */
gtk_dialog_run(GTK_DIALOG(m));
gtk_object_destroy(GTK_OBJECT(m));
}
/**
* @brief For an overview, I can describe what happens here in one sentence.
*
* Non-static functions begin with the name of the module + underscore.
* @param win Widget to work on.
* @param data Data to work with.
* @return String that has to be freed.
*/
char* module_func(GtkWidget* win, gpointer data)
{
char buf[1024];
pid_t p;
FILE* f;
/* Structuring by newlines is fine. */
f = popen(SLADINSTALLER " --ping", "r");
/* Conditional and loop intendation same as for functions. */
if(!f)
{
statfunc(_("Could not check SLAD installer."));
return;
}
else /* f != NULL */
{
statfunc(_T("An else"));
}
fgets(buf, sizeof(buf), f);
pclose(f);
#ifndef CYGWIN
/* Compiled with flag -mwindows, sladinstaller
* does not answer on stdout.
* Therefore, this test is only performed on
* non-CYGWIN systems and simply dropped for
* CYGWIN. */
if(strcmp(buf, "pong\n"))
{
statfunc(_("Could not execute SLAD installer."));
return;
}
#endif /* CYGWIN */
// Single-line intermediate comments can also start by double slashes.
p = fork();
}
_______________________________________________
Openvas-devel mailing list
Openvas-devel@wald.intevation.org
http://lists.wald.intevation.org/mailman/listinfo/openvas-devel
