search

bitlbee / bitlbee-steam

Steam protocol plugin for BitlBee
GNU General Public License v2.0
126 stars 12 forks source link

Added gtk-doc support #123

Closed vogt31337 closed 8 years ago

vogt31337 commented 8 years ago

I've added some stuff to let gtk-doc (if it's available) build the docs automagically in the folder ./doc. It's made from the examples at gtk-doc, so it should work. One thing I couldn't test is, if the code still builds if you don't have gtk-doc installed (the examples say it would work, but I couldn't easily test it). And this time I've added the gtk-doc.make script so that it won't be deleted during make clean.

Maybe it would be good to switch over to doxygen...

dgw commented 8 years ago

Oh, well I guess it's too late. Ignore my comment on #122.

jgeboski commented 8 years ago

I really do not think gtk-doc.make needs to be including in the source tree as I think it is a generated file. Also, the generated files in doc/ should be added to .gitignore.

dequis commented 8 years ago

What's the point of this? I legitimately don't get it.

vogt31337 commented 8 years ago

I'm amazed from the feedback :)

@jgeboski thx for the corrections It's my first time messing with autoconf. @dequis I wanted to provide some more documentation for users who want to understand howto write plugins the web page (https://wiki.bitlbee.org/FAQ#Are_there_docs.3F) states: "[...] But the bitlbee-steam plugin is wonderfully documented"

jgeboski commented 8 years ago

@dequis those were my first thoughts. But I figured if it can be done without breaking things as is, and without requiring GTK-Doc, I guess it is harmless. As of now, I will not merge this given that it will break things (for example: Travis) for a lot of people by adding in another dependency.

@vogt31337 Are you actually using the GTK-Doc functionality, or are you just submitting this to make it "proper"? The problem with this plugin is that there is no real API, it is all internal. That said, you kind of need the in-line documentation with the code itself. We use GTK-Doc as that is what bitlbee-facebook uses as a result of purple-facebook. And even in *-facebook it is quite pointless to generate the documentation without looking at the code. Non of this documentation actually describes the protocol, if that is what you are trying to achieve.

jgeboski commented 8 years ago

This plugin lacks any sort of documentation relating to the bitlbee plugin interface. That should be done within bitlbee, not a third party plugin.

jgeboski commented 8 years ago

In all serious, I would not put anymore effort into this patch. I am not sure it is very practical. There is a reason (explained above) why this was not done from the start when I introduced GTK-Doc.

vogt31337 commented 8 years ago

@jgeboski, okay. Then I will close the pull request. I just thought it would be nice, to have some proper docs generated. Then I will have a look at the bitlbee main project and on the plugin stuff there.

jgeboski commented 8 years ago

Thanks again!