Document function declarations in header

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Document function declarations in header

Aleksandr Slobodeniuk
Hi everyone!
 
I'm trying to generate HTMLs from one .h file, that describes some API.
In result HTML I see there's no functions, only described structs and enums.
 
Is it possible to generate documentation, if "documentation comments" are written near declaration of functions (not definitions)?
 
P.S. it's ok to scan all the code, the issue is that I would like to keep the comments in header.
 
Thanks!
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 

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

Re: Document function declarations in header

Stefan Sauer-4
On 01/29/2018 06:19 PM, Aleksandr Slobodeniuk wrote:
Hi everyone!
 
I'm trying to generate HTMLs from one .h file, that describes some API.
In result HTML I see there's no functions, only described structs and enums.
 
Is it possible to generate documentation, if "documentation comments" are written near declaration of functions (not definitions)?

It should be possible to have function doc-comments in the header. Can you put that header on some pastebin site?

Also are you manually writing the $(DOC_MODULE)-section.txt or do you let gtkdoc generate it? You can check the
$(DOC_MODULE)-decl-list.txt and $(DOC_MODULE)-decl.txt file to see if gtkdoc picked up your symbol.

 
P.S. it's ok to scan all the code, the issue is that I would like to keep the comments in header.

 
Thanks!
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 


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



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

Re: Document function declarations in header

Aleksandr Slobodeniuk
> It should be possible to have function doc-comments in the header.
 
Yes, thanls, I've found the reason of problem.
 
All function declarations had macro first, which is actually empty. Like:
_MACRO_ int my_function();
 
Gtk-doc 1.25 didn't include that functions to sections.txt/xml/html .
But if I write enter after macro, like this:
 
_MACRO_
int my_function();
 
Then it works, no matter where I'm writing the "documentation comments" (in header or code).
 
Looks like a bug in a parser.
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 
 
 
31.01.2018, 18:32, "Stefan Sauer" <[hidden email]>:
On 01/29/2018 06:19 PM, Aleksandr Slobodeniuk wrote:
Hi everyone!
 
I'm trying to generate HTMLs from one .h file, that describes some API.
In result HTML I see there's no functions, only described structs and enums.
 
Is it possible to generate documentation, if "documentation comments" are written near declaration of functions (not definitions)?

It should be possible to have function doc-comments in the header. Can you put that header on some pastebin site?

Also are you manually writing the $(DOC_MODULE)-section.txt or do you let gtkdoc generate it? You can check the
$(DOC_MODULE)-decl-list.txt and $(DOC_MODULE)-decl.txt file to see if gtkdoc picked up your symbol.
 
 
P.S. it's ok to scan all the code, the issue is that I would like to keep the comments in header.
 
Thanks!
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 
 
_______________________________________________
gtk-doc-list mailing list
[hidden email]
https://mail.gnome.org/mailman/listinfo/gtk-doc-list

 

,

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


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

Re: Document function declarations in header

Stefan Sauer-4
On 01/31/2018 04:45 PM, Aleksandr Slobodeniuk wrote:
> It should be possible to have function doc-comments in the header.
 
Yes, thanls, I've found the reason of problem.
 
All function declarations had macro first, which is actually empty. Like:
_MACRO_ int my_function();
 
Gtk-doc 1.25 didn't include that functions to sections.txt/xml/html .
But if I write enter after macro, like this:
 
_MACRO_
int my_function();
 
Then it works, no matter where I'm writing the "documentation comments" (in header or code).
 
Looks like a bug in a parser.

The parser parses 'C'. Before the preprocessor runs a c/h file is not necessarily valid. For non standard macros, you can tell gtkdoc to ignore them. Use e.g. SCAN_OPTIONS="--ignore-decorators=_MACRO_" in Makefile.am.

Stefan
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 
 
 
31.01.2018, 18:32, "Stefan Sauer" [hidden email]:
On 01/29/2018 06:19 PM, Aleksandr Slobodeniuk wrote:
Hi everyone!
 
I'm trying to generate HTMLs from one .h file, that describes some API.
In result HTML I see there's no functions, only described structs and enums.
 
Is it possible to generate documentation, if "documentation comments" are written near declaration of functions (not definitions)?

It should be possible to have function doc-comments in the header. Can you put that header on some pastebin site?

Also are you manually writing the $(DOC_MODULE)-section.txt or do you let gtkdoc generate it? You can check the
$(DOC_MODULE)-decl-list.txt and $(DOC_MODULE)-decl.txt file to see if gtkdoc picked up your symbol.
 
 
P.S. it's ok to scan all the code, the issue is that I would like to keep the comments in header.
 
Thanks!
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 
 
_______________________________________________
gtk-doc-list mailing list
[hidden email]
https://mail.gnome.org/mailman/listinfo/gtk-doc-list

 

,

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



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



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

Re: Document function declarations in header

Aleksandr Slobodeniuk
Yes, it works, thanks :)
 
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 
 
 
02.02.2018, 23:00, "Stefan Sauer" <[hidden email]>:
On 01/31/2018 04:45 PM, Aleksandr Slobodeniuk wrote:
> It should be possible to have function doc-comments in the header.
 
Yes, thanls, I've found the reason of problem.
 
All function declarations had macro first, which is actually empty. Like:
_MACRO_ int my_function();
 
Gtk-doc 1.25 didn't include that functions to sections.txt/xml/html .
But if I write enter after macro, like this:
 
_MACRO_
int my_function();
 
Then it works, no matter where I'm writing the "documentation comments" (in header or code).
 
Looks like a bug in a parser.

The parser parses 'C'. Before the preprocessor runs a c/h file is not necessarily valid. For non standard macros, you can tell gtkdoc to ignore them. Use e.g. SCAN_OPTIONS="--ignore-decorators=_MACRO_" in Makefile.am.

Stefan
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 
 
 
31.01.2018, 18:32, "Stefan Sauer" [hidden email]:
On 01/29/2018 06:19 PM, Aleksandr Slobodeniuk wrote:
Hi everyone!
 
I'm trying to generate HTMLs from one .h file, that describes some API.
In result HTML I see there's no functions, only described structs and enums.
 
Is it possible to generate documentation, if "documentation comments" are written near declaration of functions (not definitions)?

It should be possible to have function doc-comments in the header. Can you put that header on some pastebin site?

Also are you manually writing the $(DOC_MODULE)-section.txt or do you let gtkdoc generate it? You can check the
$(DOC_MODULE)-decl-list.txt and $(DOC_MODULE)-decl.txt file to see if gtkdoc picked up your symbol.
 
 
P.S. it's ok to scan all the code, the issue is that I would like to keep the comments in header.
 
Thanks!
-- 
Atentamente,
Aleksandr Slobodeniuk
tel: +34 661 674 116
 
 
 
 
_______________________________________________
gtk-doc-list mailing list
[hidden email]
https://mail.gnome.org/mailman/listinfo/gtk-doc-list

 

,

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

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

 

,

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


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

Union in struct

Aleksandr Slobodeniuk
Hi again!

I've tried to submit a bugs to bugzilla, but couldn't find gtk-doc project there (strange, yes, I submitted bugs on Gnome Bugzilla before).

So, I'll send it here, if you know how to create a ticket - I'll do it.
-----
Version 1.27
 
Bug 1.
If we have a structure, with union inside of it (as one of fields) - documentation for this field doesn't appear in HTML.
 
you can easily check it by cloning this project:
https://github.com/aslobodeniuk/gtkdoc-test
 
(master branch)

Just run ./script, and it will cleanup, compile and generate html
 
 
-----
Bug 2. (you can check it by switching the project to branch "struct_issue".
 
if we define typedef structure without enter before the "{", like this

"typedef struct _s { ... " - it appears in documentation normally.
 
If with enter before the "{", like this
"
typedef struct _s
{
...
"
 
- the whole struct doesn't appear in documentation.
 
 
------------
So... thanks for your attention.

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

Re: Union in struct

Stefan Sauer-4
On 02/05/2018 04:34 PM, Aleksandr Slobodeniuk wrote:
Hi again!

I've tried to submit a bugs to bugzilla, but couldn't find gtk-doc project there (strange, yes, I submitted bugs on Gnome Bugzilla before).

Here you go: https://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc

So, I'll send it here, if you know how to create a ticket - I'll do it.
-----
Version 1.27
 
Bug 1.
If we have a structure, with union inside of it (as one of fields) - documentation for this field doesn't appear in HTML.
 
you can easily check it by cloning this project:
https://github.com/aslobodeniuk/gtkdoc-test
 
(master branch)

Just run ./script, and it will cleanup, compile and generate html

Please report this. If you can provide this as a patch for the test suite (bugs), that'd be awesome. I'll have to run with GTKDOC_TRACE=debug and see where the parse fails.

 
 
-----
Bug 2. (you can check it by switching the project to branch "struct_issue".
 
if we define typedef structure without enter before the "{", like this

"typedef struct _s { ... " - it appears in documentation normally.
 
If with enter before the "{", like this
"
typedef struct _s
{
...
"
 
- the whole struct doesn't appear in documentation.

The parser in gtk-doc is already complicated enough. If there is an easy fix I won't mind though.

 
 
------------
So... thanks for your attention.

Thanks for the reports

Stefan



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



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