GNOME Bugzilla – Bug 585538
Add GTK-Doc comments
Last modified: 2011-03-09 17:04:58 UTC
Add GTK-Doc comments to the essential source files. At least libseahorse.
Created attachment 136408 [details] [review] seahorse-validity.c documentation Complete documentation for seahorse-validity.c
Created attachment 136551 [details] [review] Seahorse-secure-memory.c fully documented
Created attachment 136646 [details] [review] seahorse-gtkstock.c documented
Hi Thorsten, Thanks for the bug report and patches. I'm reassigning this bug to the Seahorse maintainers, since the user documentation team isn't responsible for this type of work.
Created attachment 137058 [details] [review] seahorse-gconf.c documented
Hi Shaun You are welcome. I will add more patches to the files in libseahorse soon. If anyone has special wishes please tell me.
Thorsten, You might want to have a look at the build magic for reference/libcryptui and create reference/libseahorse so that all of your hard work will show up in Devhelp.
Created attachment 137701 [details] [review] This is the magic to compile the gtk-doc content Here is the magic. More documentation coming soon
Those patches all look good. If you have a git account, feel free to commit them. If not, let me know and I'll do it. Thanks for your work.
Hi Adam You are welcome. I do not have an account yet. Would you please commit my patches ?
Adam, you told me on ICQ there is a bug in my Makefile. Can you please describe what's happening ? Or have you been able to fix it already ?
Created attachment 139297 [details] [review] seahorse-util documentation
Thorsten, Sorry I haven't been responsive lately. I'm working on finishing my PhD dissertation and moving.
Hello Adam Thats not a problem. Focus on the important stuff. I will try to reproduce the Makefile error now. If I am not able to do that, I will comment some more code. I think there is enough code for the next 4 months left. :-)
Created attachment 139697 [details] [review] seahorse-object.c documentation
Created attachment 139698 [details] [review] this fixes some gtk-doc compiler warnings
Created attachment 139699 [details] [review] maybe this fixes the compilation errors Adam, please try this fix and tell me if your errors are still there or fixed. Thanks
Thorsten, I've reworked the build files and committed your comment patches. Thanks for your work and keep it up! :)
Created attachment 141135 [details] [review] dbus specific comments Thank you Adam At the moment I try to understand how certain stuff (like dbus) works. The next few comment commits will span several files and will not be complete. I will fill the holes later.
Thorsten, I've committed your latest patch. To help me commit your patches, could you set your email address and check for trailing white space with the settings from http://live.gnome.org/Git/Developers After setting the colors, trailing white space will show up as red boxes in git diff. Have a look at what I did to the .h files you've documented already to get rid of some warnings and to the top of libseahorse/seahorse-context.c to increase the doumentation provided. Cheers.
Created attachment 141180 [details] [review] gpgme data and key operations partially comented Hi Sorry. The previous patch was created on my other computer. I forgot the settings there. This patch shold be a lot better. If still something is missing, please tell me so.
Comment on attachment 141180 [details] [review] gpgme data and key operations partially comented This patch was better, thanks. One thing we need to look at is scanning the other directories (pgp, ssh, gkr, etc.) to add their documentation as well.
Created attachment 141388 [details] [review] The patch should be already be in bugzilla. Whitespaces are fixed here. Adam Heres a previous patch, with whitespaces fixed. Just in case you want to use this and not the other. About the created documentation: I would suggest two "books". One for the internals, one for the api to other applications. The internals are for seahorse hackers, the external documentation for everyone who is using seahorse in his own projects. The last one should be simple, straight forward and contain examples if possible. my 2 cents
Comment on attachment 141388 [details] [review] The patch should be already be in bugzilla. Whitespaces are fixed here. Thanks Thorsten. I already fixed the white spaces and committed it. I'll take a look at scanning the other directories. The only public API is libcryptui and the DBus calls.
Created attachment 141578 [details] [review] gkr-keyring creation documented
Created attachment 143132 [details] [review] seahorse-gpgme-complete documentation
Created attachment 143530 [details] [review] full documentation for seahore-gpgme-generate.c
Thanks Thorsten. I've committed the remaining three patches. I don't want to dampen your enthusiasm, and your work on this is greatly appreciated ... but I don't think we need to document 'static' functions in gtk-doc. They're only used with the current module. If necessary we could put a comment above them describing what they do, but I don't feel this should be exported to gtk-doc, and thus the comment wouldn't be in gtk-doc style. Does that make sense?
Thanks for committing. I do not expect to have all my comments compiled into the documentation. I expect the public interface (libseahorse/dbus) to be documented in devhelp, nothing else. At the moment I try to fix bugs/implement enhancements. Before doing anything, I read and comment the code that is relevant for this. To know what I am doing. And I am not sad if many of my comments are only visible in the code and only help seahorse-developers. I got a macro that creates the gtk-doc comment, it is as simple to create gtk-doc comments as it is to create plain ones. - Is it ok to continue using gtk-doc style everywhere ? - Can you just include some files into the documentation compilation process and skip the others ?
Again, thanks so much for working on the documentation. This is an very valuable contribution to seahorse. I personally, would prefer it if we don't use the gtk-doc style for static functions. Here are a few reasons: * static and non-static functions share the same file. It's hard to make gtk-doc ignore just the static ones, but include the non-static ones in documentation. * In my opinion documentation of static functions is less important. These functions change far more often, and are often implementation details that are not key to understanding the entire picture of how something works. If a local comment is needed to describe better what a function does, then that's good, but I don't think it needs to be a full gtk-doc doc comment, (with each parameter and return value documented). * static functions are far more fluid, and change their implementation far more regularly. Updating more formal style gtk-doc documentation for them would become a bit of a chore in these cases. What's great is that we can build 'internal' documentation via gtk-doc compiling all the gtk-doc style comments. This does not need to show up in devhelp but is for contributors to the project. (Again static functions wouldn't be included in this internal built documentation). Though I'm one of the seahorse maintainers, it goes without saying that if you have a good reasons to challenge these opinions, please do so here, and we can work it out.
Hi Is it ok, if I document all functions, but only the non-static ones in gtk-doc style ? This way gtk-doc will ignore the static functions when compiling the documentation and any programmer will have the benefit of at least basic documentation of what a function is doing.
Created attachment 145247 [details] [review] full documentation for seahorse-service I hope this makes you happy. Static functions are documented, but not in gtk-doc style
Created attachment 145372 [details] [review] seahorse-service-crypto.c, full doc. static functions are not gtk-doc-ed
(In reply to comment #31) > Is it ok, if I document all functions, but only the non-static ones in gtk-doc > style ? > > This way gtk-doc will ignore the static functions when compiling the > documentation and any programmer will have the benefit of at least basic > documentation of what a function is doing. Yes, thats a good plan. Rock on. I've applied the two latest patches to master.
Created attachment 145578 [details] [review] seahorse-service-keyset full documentation
Created attachment 145579 [details] [review] seahorse-hkp-server full documentation More rock
Created attachment 145655 [details] [review] seahorse-sharing documented
Created attachment 145664 [details] [review] seahorse-daemon.c documentation. For the sake of completeness the last documentation for a daemon c file.
Created attachment 147448 [details] [review] seahorse-keyserver-search full documentation
Created attachment 147822 [details] [review] seahorse-widget.c full documentation
Created attachment 148223 [details] [review] updated the documentation for seahorse-source.h
Created attachment 148224 [details] [review] full documentation for seahorse-source.c
Created attachment 148546 [details] [review] Full documentation for seahorse-operation.c
I've now committed all of the patches since Stef's last comment.
Review of attachment 145247 [details] [review]: Committed
Review of attachment 145372 [details] [review]: Committed
Review of attachment 145578 [details] [review]: Committed
Review of attachment 145579 [details] [review]: Committed
Review of attachment 145655 [details] [review]: Committed
Review of attachment 145664 [details] [review]: Committed
Review of attachment 147448 [details] [review]: Committed
Review of attachment 147822 [details] [review]: Committed
Review of attachment 148546 [details] [review]: Committed
Review of attachment 148224 [details] [review]: Committed
Review of attachment 148223 [details] [review]: Committed
Hello Adam I think my documentation patches are reliable now - I will try to use my new GIT account and directly push the next documentation patch. Hope this works. Any objections ?
Thorsten: I think you can keep pushing your doc patches. I'd ask for anything involving code you still ask for review first for a while. Cheers
Exactly this is my plan. I still have to learn the Seahorse coding quirks... But I am confident-I will learn them soon.
Closing this as fixed. Thanks for the doc work Thorsten!