Created attachment 203191 [details] [review]
mkdb: change format of KnownSymbols dict

Instead of storing '1' for known public symbols and '0' for known
private/standard symbols, store the strings "public", "standard" and
"private", accordingly.

Created attachment 203192 [details] [review]
mkdb: recognise GObjects in 'standard'

Only ignore GObject types if they are in Private subsections.  Do the
normal GObject introspection stuff for those included in Standard.

This is the beginning of an idea of how we might want to handle this.  It's currently broken due to (I think) this code:

  # We don't want standard macros/functions of GObjects,
  # or private declarations.
  if ($subsection ne "Standard" && $subsection ne "Private") {


in OutputSGML() that I'm scared to modify...

I have GObjects that do intentionally have public data members, marked /*<public>*/, of course to get them documented.  I do not want them disappear, thank you very much.

Also, that the standard stuff is not mentioned at all seems to be confusing to some novice users of the libs.  Removing more means increasing the confusion.

So, IMO, this is heading in an entirely wrong direction.  Instead, the documentation of the standard symbols should be automatically created if there is no manual documentation overridng it -- see bug 166363.

+1 for what Yeti said. I would be open to have a commandline switch to choose a different policy if one can come up with a simple enough scheme. I don't want 10 new options for it really.

(In reply to comment #4)
> I have GObjects that do intentionally have public data members, marked
> /*<public>*/, of course to get them documented.  I do not want them disappear,
> thank you very much.

That's not what Ryan's patch does (assuming I'm reading it correctly). It adds the *option* of omitting the struct entry (while still documenting the signals, hierarchy, etc), but it also keeps the two existing options (to show everything, or to show nothing).

In Ryan's patch, the new option is triggered by putting the struct into <SUBSECTION Standard>, but that used to be equivalent to putting it in <SUBSECTION Private>, so this might change the behavior in some modules where people intended for the type to be hidden...

Review of attachment 203191 [details] [review]:

::: gtkdoc-mkdb.in
@@ +1195,3 @@
             }
             else {
+                $KnownSymbols{$symbol} = $subsection;

lc $subsection

(In reply to comment #7)
> Review of attachment 203191 [details] [review]:
> 
> ::: gtkdoc-mkdb.in
> @@ +1195,3 @@
>              }
>              else {
> +                $KnownSymbols{$symbol} = $subsection;
> 
> lc $subsection

Or alternatively also use the form with a leading uppercase character (maybe more consistent).

(In reply to comment #3)
> This is the beginning of an idea of how we might want to handle this.  It's
> currently broken due to (I think) this code:
> 
>   # We don't want standard macros/functions of GObjects,
>   # or private declarations.
>   if ($subsection ne "Standard" && $subsection ne "Private") {
> 
> 
> in OutputSGML() that I'm scared to modify...

How is it broken? You probably want to ensure that
if (&CheckIsObject ($symbol)) {
    push @file_objects, $symbol;
}
is now called for both "Public" and "Standard".

So what is the plan? Regarding policy, there is also: bug#324880.

With current git (upcomming 1.20), gtkdoc-scan is only adding Object, ObjectClass and ObjectIface/Interface to the public subsection of the autogenerated section file if they are actually documented. Personally I put the ObjectClass to the standart subsection in my manual section file for some time already if there is nothing there to be documented.

Ryan, are you saying that if an object has neither Object nor ObjectClass documented it is not showing up as a GObject in the docs (not properties, signals, hierarchy, ...)?

I added a testcase and push a simple fix. Now gobject that have section docs show up with all details.

commit 457c8bb87ea05d4da5f08f33b4799c0622cca0c2
Author: Stefan Sauer <ensonic@users.sf.net>
Date:   Fri Feb 14 21:15:09 2014 +0100

    mkdb: show object details also for mostly undocumented objects
    
    Simplyfy the code. If there is a section entry for an object, show the object
    details and the docs we have.
    Fixes #593282

commit 28380a862cfa50725a9b69f5004ce04edb5f91fb
Author: Stefan Sauer <ensonic@users.sf.net>
Date:   Fri Feb 14 21:14:23 2014 +0100

    tests: add a undocumented object
    
    Test case for bug#593282