Warning in XML build phase

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

Warning in XML build phase

Emmanuel Pacaud-3
Hi,

I've added gtk-doc support to the Lasem library
(http://git.gnome.org/browse/lasem/). But when I build the
documentation, I've got a the following warnings:

gtk-doc: Running scanner lasem-scan
gtk-doc: Building XML
:0: warning: Field descriptions for LsmSvgRadialGradientElementClass are
missing in source code comment block.
:0: warning: Value descriptions for LsmMathmlRadicalElementType are
missing in source code comment block.
:0: warning: Field descriptions for LsmMathmlRadicalElementClass are
missing in source code comment block.
:0: warning: Field descriptions for LsmSvgTspanElementClass are missing
in source code comment block.
:0: warning: Field descriptions for LsmSvgLinearGradientElementClass are
missing in source code comment block.
:0: warning: Field descriptions for LsmMathmlDocumentClass are missing
in source code comment block.
:0: warning: Field descriptions for LsmSvgPatternElementClass are
missing in source code comment block.

...And a lot more...

I don't understand the meaning of this warnings, as I didn't have
documented these structures at all.

Any idea ?

Thanks in advance,

Emmanuel.

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

Re: Warning in XML build phase

Stefan Sauer-4
Am 29.10.2010 15:49, schrieb Emmanuel Pacaud:

> Hi,
>
> I've added gtk-doc support to the Lasem library
> (http://git.gnome.org/browse/lasem/). But when I build the
> documentation, I've got a the following warnings:
>
> gtk-doc: Running scanner lasem-scan
> gtk-doc: Building XML
> :0: warning: Field descriptions for LsmSvgRadialGradientElementClass are
> missing in source code comment block.
> :0: warning: Value descriptions for LsmMathmlRadicalElementType are
> missing in source code comment block.
> :0: warning: Field descriptions for LsmMathmlRadicalElementClass are
> missing in source code comment block.
> :0: warning: Field descriptions for LsmSvgTspanElementClass are missing
> in source code comment block.
> :0: warning: Field descriptions for LsmSvgLinearGradientElementClass are
> missing in source code comment block.
> :0: warning: Field descriptions for LsmMathmlDocumentClass are missing
> in source code comment block.
> :0: warning: Field descriptions for LsmSvgPatternElementClass are
> missing in source code comment block.
>
> ...And a lot more...


Your section.txt file looks wrong.
http://git.gnome.org/browse/lasem/tree/docs/reference/lasem/lasem-sections.txt

Change e.g.
<SECTION>
<FILE>lsmmathmlradicalelement</FILE>
<TITLE>LsmMathmlRadicalElement</TITLE>
LsmMathmlRadicalElementType
LsmMathmlRadicalElementClass
LsmMathmlRadicalElement
lsm_mathml_root_element_new
lsm_mathml_sqrt_element_new
<SUBSECTION Standard>
LSM_MATHML_RADICAL_ELEMENT
LSM_IS_MATHML_RADICAL_ELEMENT
LSM_TYPE_MATHML_RADICAL_ELEMENT
lsm_mathml_radical_element_get_type
LSM_MATHML_RADICAL_ELEMENT_CLASS
LSM_IS_MATHML_RADICAL_ELEMENT_CLASS
LSM_MATHML_RADICAL_ELEMENT_GET_CLASS
</SECTION>

to

<SECTION>
<FILE>lsmmathmlradicalelement</FILE>
<TITLE>LsmMathmlRadicalElement</TITLE>
LsmMathmlRadicalElement
lsm_mathml_root_element_new
lsm_mathml_sqrt_element_new
<SUBSECTION Standard>
LsmMathmlRadicalElementType
LsmMathmlRadicalElementClass
LSM_MATHML_RADICAL_ELEMENT
LSM_IS_MATHML_RADICAL_ELEMENT
LSM_TYPE_MATHML_RADICAL_ELEMENT
lsm_mathml_radical_element_get_type
LSM_MATHML_RADICAL_ELEMENT_CLASS
LSM_IS_MATHML_RADICAL_ELEMENT_CLASS
LSM_MATHML_RADICAL_ELEMENT_GET_CLASS
</SECTION>

If you don't put e.g. LsmMathmlRadicalElementClass, gtk-doc naturally expects
you to document it :)

Stefan


>
> I don't understand the meaning of this warnings, as I didn't have
> documented these structures at all.
>
> Any idea ?
>
> Thanks in advance,
>
> Emmanuel.
>
> _______________________________________________
> gtk-doc-list mailing list
> [hidden email]
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list

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

Re: Warning in XML build phase

Emmanuel Pacaud-3
Hi Stefan,

> If you don't put e.g. LsmMathmlRadicalElementClass, gtk-doc naturally expects
> you to document it :)

Thanks a lot for your answer. I've fixed lasem and get rid of all the
warnings.

I think the warning message doesn't explain clearly what's wrong, and
doesn't help to fix them. And I don't get the point of such warnings.
The content of foo-undocumented.txt should be enough, no ?

Also, the sections file was mostly autogenerated. It would be better if
at least the FooClass structures are automatically placed in the
Standard subsection.

Thanks again,

Emmanuel.

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

Re: Warning in XML build phase

Stefan Sauer-4
Am 30.10.2010 14:39, schrieb Emmanuel Pacaud:

> Hi Stefan,
>
>> If you don't put e.g. LsmMathmlRadicalElementClass, gtk-doc naturally expects
>> you to document it :)
>
> Thanks a lot for your answer. I've fixed lasem and get rid of all the
> warnings.
>
> I think the warning message doesn't explain clearly what's wrong, and
> doesn't help to fix them. And I don't get the point of such warnings.
> The content of foo-undocumented.txt should be enough, no ?

The point of the warning is to say, that something is expected to be documented,
but it is not. The warning can probably be improved, but might become a bit
longish. I could add it to the FAQ also.

>
> Also, the sections file was mostly autogenerated. It would be better if
> at least the FooClass structures are automatically placed in the
> Standard subsection.

If you want to use an autogenerated section file, you need to document standard
parts right now. I take patches for smarter section.txt generation. Anyway the
plan is actually to get rid of the file and just use yet-another keyword in the
docs to tell if a symbol should be part of a specific section (as an exception
for not in the current section).

Stefan

>
> Thanks again,
>
> Emmanuel.
>

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