Re: [patch] kgdb light, v6

[Bartlomiej Zolnierkiewicz <bzolnier@gmail.com>]

On Sunday 10 February 2008, Ingo Molnar wrote:

[...]

> > > +/*
> > > + *	kgdb_get_shadow_thread - Get the shadowed &task_struct of @threadid.
> > > + *	@regs: The &struct pt_regs of the current thread.
> > > + *	@threadid: The thread id of the shadowed process to get information on.
> > > + *
> > > + *	RETURN:
> > > + *	This returns a pointer to the &struct task_struct of the shadowed
> > > + *	thread, @threadid.
> > > + */
> > > +extern struct task_struct *kgdb_get_shadow_thread(struct pt_regs *regs,
> > > +						  int threadid);
> > 
> > So we have kerneldoc comments in both places now?  Didn't you say
> > you converted these to something else?
> 
> no. These are not DocBook comments, if you look carefully at the format 
> [it's not a leading '/**' comment block]. But obviously documenting this 
> in the include file is very useful, because that's where people look 
> first, so i kept it. (the APIs will not deviate across architectures)

comments and variable names in include files have a tendency for going
out-of-sync in the long term so IMO having a DocBook to point people at
would be a better solution (+ it would shrink <linux/kgdb.h> by 122 lines)

while at it:

--- x86/kernel/kgdb.c	2008-02-10 20:30:39.000000000 +0100
+++ linux/kgdb.h	2008-02-10 20:25:21.000000000 +0100
@@ -128,11 +131,13 @@
  *	process more packets, and a %0 or %1 if it wants to exit from the
  *	kgdb callback.
  */
-int kgdb_arch_handle_exception(int e_vector, int signo, int err_code,
-			       char *remcomInBuffer, char *remcomOutBuffer,
-			       struct pt_regs *linux_regs)
+extern int
+kgdb_arch_handle_exception(int vector, int signo, int err_code,
+			   char *remcom_in_buffer,
+			   char *remcom_out_buffer,
+			   struct pt_regs *regs);