[PATCH] Add doc-comment to get_domain_by_id

[PATCH] Add doc-comment to get_domain_by_id

[Mats Petersson]

# HG changeset patch
# User Mats Petersson <mats.petersson@citrix.com>
# Date 1358516011 0
# Node ID 9662deb217d7869d35dce5587ae8a1b45296b3a0
# Parent  126ce5f1855ba21ae24fc1c0981e5c05a3245bad
Add doc-comment to get_domain_by_id

diff --git a/xen/common/domain.c b/xen/common/domain.c
--- a/xen/common/domain.c
+++ b/xen/common/domain.c
@@ -373,7 +373,16 @@
     free_cpumask_var(cpumask);
 }
 
-
+/**
+ * This function finds a domain from a domain id. The domain's
+ * reference count is incremented as part of this function.
+ * The caller must call put_domain to un-reference the domain.
+ *
+ * @param dom       Domain ID of the domain to be found.
+ *
+ * @return         On success the pointer to a struct domain.
+ *                 On failure, return NULL.
+ */
 struct domain *get_domain_by_id(domid_t dom)
 {
     struct domain *d;

Re: [PATCH] Add doc-comment to get_domain_by_id

[Mats Petersson]

On 18/01/13 13:34, Mats Petersson wrote:
> # HG changeset patch
> # User Mats Petersson <mats.petersson@citrix.com>
> # Date 1358516011 0
> # Node ID 9662deb217d7869d35dce5587ae8a1b45296b3a0
> # Parent  126ce5f1855ba21ae24fc1c0981e5c05a3245bad
> Add doc-comment to get_domain_by_id
>
> diff --git a/xen/common/domain.c b/xen/common/domain.c
> --- a/xen/common/domain.c
> +++ b/xen/common/domain.c
> @@ -373,7 +373,16 @@
>       free_cpumask_var(cpumask);
>   }
>   
> -
> +/**
> + * This function finds a domain from a domain id. The domain's
> + * reference count is incremented as part of this function.
> + * The caller must call put_domain to un-reference the domain.
> + *
> + * @param dom       Domain ID of the domain to be found.
> + *
> + * @return         On success the pointer to a struct domain.
> + *                 On failure, return NULL.
> + */
>   struct domain *get_domain_by_id(domid_t dom)
>   {
>       struct domain *d;
>
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org
> http://lists.xen.org/xen-devel
>
>
Sorry for the badly formatted patch - will submit a V2 with "better" 
formatting & signed off... "hg email" is a bit different to "git 
send-email", I just learned... ;)

--
Mats

Re: [PATCH] Add doc-comment to get_domain_by_id

[Ian Campbell]

On Fri, 2013-01-18 at 13:34 +0000, Mats Petersson wrote:
> # HG changeset patch
> # User Mats Petersson <mats.petersson@citrix.com>
> # Date 1358516011 0
> # Node ID 9662deb217d7869d35dce5587ae8a1b45296b3a0
> # Parent  126ce5f1855ba21ae24fc1c0981e5c05a3245bad
> Add doc-comment to get_domain_by_id
> 
> diff --git a/xen/common/domain.c b/xen/common/domain.c
> --- a/xen/common/domain.c
> +++ b/xen/common/domain.c

We normally put these comments in the header next to the protoype.

> @@ -373,7 +373,16 @@
>      free_cpumask_var(cpumask);
>  }
>  
> -
> +/**

Nothing in the Xen infrastructure parses these sorts of headers and
practically nowhere else uses them. I'd say just make this a regular
comment.

Ian.

Re: [PATCH] Add doc-comment to get_domain_by_id

[Mats Petersson]

On 18/01/13 14:02, Ian Campbell wrote:
> On Fri, 2013-01-18 at 13:34 +0000, Mats Petersson wrote:
>> # HG changeset patch
>> # User Mats Petersson <mats.petersson@citrix.com>
>> # Date 1358516011 0
>> # Node ID 9662deb217d7869d35dce5587ae8a1b45296b3a0
>> # Parent  126ce5f1855ba21ae24fc1c0981e5c05a3245bad
>> Add doc-comment to get_domain_by_id
>>
>> diff --git a/xen/common/domain.c b/xen/common/domain.c
>> --- a/xen/common/domain.c
>> +++ b/xen/common/domain.c
> We normally put these comments in the header next to the protoype.
Ok, I can move it... ;)
>
>> @@ -373,7 +373,16 @@
>>       free_cpumask_var(cpumask);
>>   }
>>   
>> -
>> +/**
> Nothing in the Xen infrastructure parses these sorts of headers and
> practically nowhere else uses them. I'd say just make this a regular
> comment.
And there I was searching for "how do you do doxygen style comments" 
after having written a normal one, just so I could avoid being told that 
"You should use doxygen format... " ;) I guess that's why I couldn't 
trivially find something.

--
Mats
>
> Ian.
>