Field description is missing in source code comment block.

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Field description is missing in source code comment block.

Takao Fujiwara
When I try to build xml, I got the following error about IBusPropList::properties:

../../../src/ibusproplist.h:73: warning: Field description for IBusPropList::properties is missing in source code comment block.

https://github.com/ibus/ibus/blob/master/src/ibusproplist.h#L73
/**
 * IBusPropList:
 * @properties: GArray that holds IBusProperties.
 *
 * An array of IBusProperties.
 */
struct _IBusPropList {
    IBusSerializable parent;

    /*< public >*/
    GArray *properties;
};

How can I resolve this warning?


_______________________________________________
gtk-doc-list mailing list
[hidden email]
https://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Field description is missing in source code comment block.

Stefan Sauer-4
On 07/03/2015 12:59 PM, Takao Fujiwara wrote:
When I try to build xml, I got the following error about IBusPropList::properties:

../../../src/ibusproplist.h:73: warning: Field description for IBusPropList::properties is missing in source code comment block.

https://github.com/ibus/ibus/blob/master/src/ibusproplist.h#L73
/**
 * IBusPropList:
 * @properties: GArray that holds IBusProperties.
 *
 * An array of IBusProperties.
 */
struct _IBusPropList {
    IBusSerializable parent;

    /*< public >*/
    GArray *properties;
};

How can I resolve this warning?
This looks correct, what gtkdoc versiona re you using (e.g. gtkdoc-mkdb --version). Btw, while looking at your code, this comment is wrong:
/**
 * ibus_prop_list_new:
 * @returns: A newly allocated IBusPropList.
 *
 * New a IBusPropList.
 */

It should be
/**
 * ibus_prop_list_new:
 *
 * Create a new IBusPropList.
 *
 * Returns: A newly allocated IBusPropList.
  */


_______________________________________________
gtk-doc-list mailing list
[hidden email]
https://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Field description is missing in source code comment block.

Takao Fujiwara
On 07/04/15 00:01, Stefan Sauer-san wrote:

> On 07/03/2015 12:59 PM, Takao Fujiwara wrote:
>> When I try to build xml, I got the following error about IBusPropList::properties:
>>
>> ../../../src/ibusproplist.h:73: warning: Field description for IBusPropList::properties is missing in source code comment block.
>>
>> https://github.com/ibus/ibus/blob/master/src/ibusproplist.h#L73
>> /**
>>   * IBusPropList:
>>   * @properties: GArray that holds IBusProperties.
>>   *
>>   * An array of IBusProperties.
>>   */
>> struct _IBusPropList {
>>      IBusSerializable parent;
>>
>>      /*< public >*/
>>      GArray *properties;
>> };
>>
>> How can I resolve this warning?
> This looks correct, what gtkdoc versiona re you using (e.g. gtkdoc-mkdb --version). Btw, while looking at your code, this comment is wrong:

Thanks for your reply. The version is 1.23
gtk-doc-1.23-1.fc22.noarch

When I run gtkdoc-mkdb for ibusproplist.[c|h] only, the warning is not shown.
So probably this problem is caused by the nested included files of ibus c and h files.
I need to have a furthermore investigation but the debug of gtkdoc-scan, gtkdoc-scangobj, gtkdoc-mktmpl, gtkdoc-mkdb are a little complicated for me.
This problem can be seen when I just run make on the top of the source directory.


> /**
>   * ibus_prop_list_new:
>   * @returns: A newly allocated IBusPropList.
>   *
>   * New a IBusPropList.
>   */
>
> It should be
> /**
>   * ibus_prop_list_new:
>   *
>   * Create a new IBusPropList.
>   *
>   * Returns: A newly allocated IBusPropList.
> */

OK, I see.

_______________________________________________
gtk-doc-list mailing list
[hidden email]
https://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Field description is missing in source code comment block.

Takao Fujiwara
On 07/07/15 19:28, Takao Fujiwara-san wrote:

> On 07/04/15 00:01, Stefan Sauer-san wrote:
>> On 07/03/2015 12:59 PM, Takao Fujiwara wrote:
>>> When I try to build xml, I got the following error about IBusPropList::properties:
>>>
>>> ../../../src/ibusproplist.h:73: warning: Field description for IBusPropList::properties is missing in source code comment block.
>>>
>>> https://github.com/ibus/ibus/blob/master/src/ibusproplist.h#L73
>>> /**
>>>   * IBusPropList:
>>>   * @properties: GArray that holds IBusProperties.
>>>   *
>>>   * An array of IBusProperties.
>>>   */
>>> struct _IBusPropList {
>>>      IBusSerializable parent;
>>>
>>>      /*< public >*/
>>>      GArray *properties;
>>> };
>>>
>>> How can I resolve this warning?
>> This looks correct, what gtkdoc versiona re you using (e.g. gtkdoc-mkdb --version). Btw, while looking at your code, this comment is wrong:
>
> Thanks for your reply. The version is 1.23
> gtk-doc-1.23-1.fc22.noarch
>
> When I run gtkdoc-mkdb for ibusproplist.[c|h] only, the warning is not shown.
> So probably this problem is caused by the nested included files of ibus c and h files.
> I need to have a furthermore investigation but the debug of gtkdoc-scan, gtkdoc-scangobj, gtkdoc-mktmpl, gtkdoc-mkdb are a little complicated for me.
> This problem can be seen when I just run make on the top of the source directory.

Finally I understood this issue is caused because IBusPropList is also defined in ibusproperty.h to be able to include ibusproplist.h and
ibusproperty.h each other:
https://github.com/ibus/ibus/blob/master/src/ibusproperty.h#L121

Now I moved the line of "typedef struct _IBusPropList IBusPropList" to ibustypes.h likes gtk and resolved this issue.

Thanks.
_______________________________________________
gtk-doc-list mailing list
[hidden email]
https://mail.gnome.org/mailman/listinfo/gtk-doc-list
Loading...