Re: [PATCH 22/24] mpt fusion: [2.6.30-rc6]Added support for Broadcast primitives Event handling

[James Bottomley <James.Bottomley@HansenPartnership.com>]

On Fri, 2009-05-22 at 16:41 +0530, Kashyap, Desai wrote:
> @@ -4314,6 +4333,182 @@ mptsas_send_raid_event(struct fw_event_work *fw_event)
>  		mptsas_free_fw_event(ioc, fw_event);
>  }
>  
> +/**
> + *	mptsas_issue_tm - send mptsas internal tm request
> + *	@ioc: Pointer to MPT_ADAPTER structure
> + *	@type
> + *	@channel
> + *	@id
> + *	@lun
> + *	@task_context
> + *	@timeout
> + *
> + *	return:
> + *
> + **/

That's not really very descriptive, is it?

> +/**
> + * mptscsih_get_scsi_lookup
> + *
> + * retrieves scmd entry from ScsiLookup[] array list
> + *
> + * @ioc: Pointer to MPT_ADAPTER structure
> + * @i: index into the array
> + *
> + * Returns the scsi_cmd pointer
> + *
> + **/

This is nicely descriptive, but it isn't legal docbook.  That should be

/**
 * mptscsih_get_scsi_lookup - retrieve scmd entry from ScsiLookup[] array list
 * @ioc: Pointer to MPT_ADAPTER structure
 * @i: index into the array
etc...

Nor is this:

> +/**
> + *     mptsas_broadcast_primative_work - Work queue thread to handle
> + *     broadcast primitive events
> + *     @work: work queue payload containing info describing the event
> + *
> + **/

The initial description needs to be all on one line, not split across
two.

James



James