GNOME Bugzilla – Bug 676856
Build reference docs
Last modified: 2013-03-14 23:42:38 UTC
Now that we've ported mutter's docs to GTK+ doc syntax, why not build them?
Created attachment 215021 [details] [review] Build reference docs
Note that after trying it out, there are still a lot of warnings that need to be fixed, and the API isn't as good as it could be.
Review of attachment 215021 [details] [review]: Missing mutter-docs.sgml - doesn't build. What is included looks fine. > Note that after trying it out: there are still a lot of warnings that need to > be fixed, and the API isn't as good as it could be. Lot of warnings need to be fixed - prerequisite for landing this patch is to have warnings clean (do a separate followup docs-cleanup patch) the API isn't as good as it could be - of course :-) ... not really related to whether it has docs.
Created attachment 236284 [details] [review] Build reference docs Rebased
Created attachment 236285 [details] [review] Escape a few < and > from the API docs
Created attachment 236286 [details] [review] Remove meta_display_get_atom and MetaAtom They aren't used and MetaAtom confused gtk-doc because it's defined with a macro.
Created attachment 236287 [details] [review] Fix gobs of gtk-doc warnings
Created attachment 236288 [details] [review] Ignore private headers when generating API docs
Sorry, just realized we still get warnings when fixing cross-references. More to come, but not today.
Created attachment 236587 [details] [review] docs: Fix cross-reference generation
These are the remaining warnings, some caused by references to APIs for which there's no gtk-doc docs and the rest by references to private symbols from the public API docs. Suggestions about how to deal with these are welcome. ./meta-unused.txt:1: warning: 1 unused declarations.They should be added to meta-sections.txt in the appropriate place. DOC Building HTML Computing chunks... DOC Fixing cross-references html/meta-MetaCompositor.html:52: warning: no link for: 'XEvent' -> (<span class="type">XEvent</span>). html/meta-util.html:128: warning: no link for: 'meta-display-open' -> (<code class="function">meta_display_open()</code>). html/meta-group.html:46: warning: no link for: 'Window' -> (<span class="type">Window</span>). html/meta-window.html:127: warning: no link for: 'XConfigureEvent' -> (<span class="type">XConfigureEvent</span>). html/meta-prefs.html:107: warning: no link for: 'XIDeviceEvent' -> (<span class="type">XIDeviceEvent</span>). html/MetaPlugin.html:68: warning: no link for: 'Cursor' -> (<span class="type">Cursor</span>). html/meta-compositor-mutter.html:52: warning: no link for: 'XserverRegion' -> (<span class="type">XserverRegion</span>). html/meta-main.html:68: warning: no link for: 'event-callback' -> (<code class="function">event_callback()</code>). html/meta-common.html:45: warning: no link for: 'Display' -> (<span class="type">Display</span>). html/MetaShapedTexture.html:56: warning: no link for: 'Pixmap' -> (<span class="type">Pixmap</span>). html/meta-screen.html:57: warning: no link for: 'Screen' -> (<span class="type">Screen</span>). html/meta-screen.html:267: warning: no link for: 'SnStartupSequence' -> (<span class="type">SnStartupSequence</span>). html/meta-display.html:684: warning: no link for: 'mutter-begin-modal-for-plugin' -> (<code class="function">mutter_begin_modal_for_plugin()</code>). html/MetaBackgroundActor.html:97: warning: no link for: 'MetaWindowGroup' -> (<span class="type">MetaWindowGroup</span>).
Created attachment 236919 [details] [review] Build reference docs
Created attachment 236920 [details] [review] Escape a few < and > from the API docs
Created attachment 236921 [details] [review] Remove meta_display_get_atom and MetaAtom They aren't used and MetaAtom confused gtk-doc because it's defined with a macro.
Created attachment 236922 [details] [review] Fix gobs of gtk-doc warnings
Created attachment 236923 [details] [review] Ignore private headers when generating API docs
Created attachment 236924 [details] [review] docs: Fix cross-reference generation
Created attachment 236925 [details] [review] Update doc generation because fo recent changes
Attachment 236919 [details] pushed as a382698 - Build reference docs Attachment 236920 [details] pushed as 9281a1c - Escape a few < and > from the API docs Attachment 236921 [details] pushed as edeac1d - Remove meta_display_get_atom and MetaAtom Attachment 236922 [details] pushed as e0b698d - Fix gobs of gtk-doc warnings Attachment 236923 [details] pushed as 2863eba - Ignore private headers when generating API docs Attachment 236924 [details] pushed as be46869 - docs: Fix cross-reference generation Thanks. Talking with Owen today, he decided we should update these.