Re: [i-g-t 6/7] lib: various documentation fixes

[Daniel Vetter <daniel@ffwll.ch>]

On Tue, Jun 10, 2014 at 03:30:56PM +0100, Thomas Wood wrote:
> Fix some documentation comments and mark some struct members private.
> 
> Signed-off-by: Thomas Wood <thomas.wood@intel.com>
> ---
>  lib/igt_aux.c           |  5 ++---
>  lib/igt_core.c          | 10 +++++-----
>  lib/igt_kms.h           |  2 ++
>  lib/intel_batchbuffer.h |  5 +----
>  4 files changed, 10 insertions(+), 12 deletions(-)
> 
> diff --git a/lib/igt_aux.c b/lib/igt_aux.c
> index c0088d5..7b277be 100644
> --- a/lib/igt_aux.c
> +++ b/lib/igt_aux.c
> @@ -430,10 +430,9 @@ bool igt_setup_runtime_pm(void)
>  }
>  
>  /**
> - * igt_runtime_pm_status:
> + * igt_get_runtime_pm_status:
>   *
> - * Returns:
> - * The current runtime PM status.
> + * Returns: The current runtime PM status.
>   */
>  enum igt_runtime_pm_status igt_get_runtime_pm_status(void)
>  {
> diff --git a/lib/igt_core.c b/lib/igt_core.c
> index 56eacf2..7ac7ebe 100644
> --- a/lib/igt_core.c
> +++ b/lib/igt_core.c
> @@ -1031,11 +1031,11 @@ static void fatal_sig_handler(int sig)
>   * @fn: exit handler function
>   *
>   * Set a handler that will be called either when the process calls exit() or
> - * returns from the main function, or one of the signals in 'handled_signals'
> - * is raised. MAX_EXIT_HANDLERS handlers can be installed, each of which will
> - * be called only once, even if a subsequent signal is raised. If the exit
> - * handlers are called due to a signal, the signal will be re-raised with the
> - * original signal disposition after all handlers returned.
> + * <!-- -->returns from the main function, or one of the signals in

Ugh, this is ugly. Maybe put a "prevent gtkdoc from parsing the returns"
into the html comment block?

> + * 'handled_signals' is raised. MAX_EXIT_HANDLERS handlers can be installed,
> + * each of which will be called only once, even if a subsequent signal is
> + * raised. If the exit handlers are called due to a signal, the signal will be
> + * re-raised with the original signal disposition after all handlers returned.
>   *
>   * The handler will be passed the signal number if called due to a signal, or
>   * 0 otherwise. Exit handlers can also be used from test children spawned with
> diff --git a/lib/igt_kms.h b/lib/igt_kms.h
> index 8e80d4b..17bf0a2 100644
> --- a/lib/igt_kms.h
> +++ b/lib/igt_kms.h
> @@ -99,6 +99,7 @@ typedef struct igt_pipe igt_pipe_t;
>  typedef uint32_t igt_fixed_t;			/* 16.16 fixed point */
>  
>  typedef struct {
> +	/*< private >*/
>  	igt_pipe_t *pipe;
>  	int index;
>  	unsigned int is_primary       : 1;
> @@ -127,6 +128,7 @@ struct igt_pipe {
>  };
>  
>  typedef struct {
> +	/*< private >*/
>  	igt_display_t *display;
>  	uint32_t id;					/* KMS id */
>  	struct kmstest_connector_config config;
> diff --git a/lib/intel_batchbuffer.h b/lib/intel_batchbuffer.h
> index 49dbcf0..3715161 100644
> --- a/lib/intel_batchbuffer.h
> +++ b/lib/intel_batchbuffer.h
> @@ -204,14 +204,10 @@ void intel_copy_bo(struct intel_batchbuffer *batch,
>   * @tiling: tiling mode bits
>   * @data: pointer to the memory mapping of the buffer
>   * @size: size of the buffer object
> - * @num_tiles: number of tiles of the buffer object
>   *
>   * This is a i-g-t buffer object wrapper structure which augments the baseline
>   * libdrm buffer object with suitable data needed by the render copy and the
>   * media fill functions.
> - *
> - * Note that @num_tiles is only used by gem_stress.c internally and can be
> - * ignored.
>   */
>  struct igt_buf {
>      drm_intel_bo *bo;
> @@ -219,6 +215,7 @@ struct igt_buf {
>      uint32_t tiling;
>      uint32_t *data;
>      uint32_t size;
> +    /*< private >*/
>      unsigned num_tiles;
>  };
>  
> -- 
> 1.9.3
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch