Source code documentation
Hello to the other developers, I finally got a working build environment set up on my Ubuntu machine here and have been perusing the sourcecode a bit. So far I like what I am seeing, the program makes use of the standard template library to avoid messy data structure code and the class structure seems to make pretty good use of public/private access to promote modularity.
The thing that really seems to be lacking though is a good organizational structure between the .h and .cpp files, as well as a lack of function documentation. I would be happy to start writing documentation for the functions using the doxygen documentation system. I am using this on OpenDungeons which is a game I am the lead coder on and it has served me well.
For those that are unfamiliar with it, Doxygen works by reading your sourcefiles to extract information which it automatically collects (like function parameters, class organization and inheritance, etc), as well as information you add yourself (comments describing what functions do, what variables are used for, etc). After it parses all of the code it produces a directory containing a bunch of HTML files which are very well crosslinked and easy to navigate. It can also be configured to autogenerate neat little call graphs showing what subfunctions are called from each function (so you can trace dependancies/bugs).
All in all Doxygen is an excellent system and I would be happy to get it set up and begin writing documentation for the functions (at least the ones I can figure out anyway) and provide patches so they can be uploaded to SVN. I don’t want to do this though if other developers would be opposed to it so I wanted to post here before I got started. Let me know if you would like me to do this.
EDIT: In case people want to see what the documentation on an existing system looks like, here is a link to the documentation for the OGRE 3d rendering system. The best place to get a feel for the documentation is to click the “Classes” link at the top and then look at the pages for a couple of classes.
-Buck
I think that would be cool, but as always, the decision rests with Satoshi, the project lead.
Quote from: lachesis on July 15, 2010, 11:57:19 PM
I think that would be cool, but as always, the decision rests with Satoshi, the project lead.
I didn’t think this would be something people would object to. Hopefully I hear definitively from Satoshi that it is OK. I will probably start working on this tonight then (tonight in USA time). Also, I saw another thread questioning how to send in patches; the stated answer was that we should e-mail them to Satoshi, is this still the preferred method?
-Buck
I like that in libraries for the external API’s, but you can probably tell from the code that I’m not a fan of it for interior functions. Big obligatory comment headers for each function space out the code and make you hesitate about creating a small little function where the comment header would be bigger than the function. They’re some trouble for maintenance, as changes to the function then require duplicate changes in the comment header. I like to keep code compact so you can see more code on the screen at once.
To add them now at this point, what would be written would just be what’s obvious from looking at the function.
The external API we have, in rpc.cpp, the usage documentation is in the help string.
Sorry to be a wet blanket.
No problem, that is why I asked about documentation before I started writing it. I still would like to document it though and maybe we can come to some system which you would find acceptable. One possible way is that I just run Doxygen on my own code and just use the auto-generated docs without adding any descriptions, etc. This would have no impact on the project and myself or anyone else could do this whenever but it limits the usefulness of the documentation.
A second, and perhaps more appealing method would be to utilize the fact that Doxygen does not require the added documentation to be in the same file as the source code it is documenting. We could add a single file that contains the documentation blocks with links pointing to the function names. Doxygen then combines this with the auto-generated info it collects from the source to produce the docs.
Finally, whether we use Doxygen or not, I would like to write a “man page” for the program documenting the command-line options it takes. Where is the command line processed in the code? I looked at main.cpp and didn’t see it (in fact I couldn’t even find the “main” function).
-Buck
It’s in init.cpp.
It’s a wxWidgets app, so it doesn’t have a main() function. It may in a little while, since I’m pretty close to making bitcoind build w/o wxBase. (it’ll be in init.cpp)
Sorry about my choice of the filename “main.cpp”, another possible name would have been “core.cpp”. It’s much too late to change. I still prefer main.cpp.
We’re still in great need of sample code showing the recommended way to use the JSON-RPC functions, like for a basic account system on a typical storefront website. Using getreceivedbylabel using the username as the label, changing to a new bitcoin address once the stored one for that account gets used. I posted a sample code fragment on the forum somewhere. (search on getreceivedbylabel or getnewaddress) The sample code could be a plain vanilla bank site where you can deposit and send payments.
Sorry to keep replying to myself but I am posting these little snippets as I stumble across them. I am currently documenting the -dropmessagestest command line switch and I see a minor improvement you may want to add to the code. Currently if a message is dropped as a result of this switch, a debug message is printed to the log indicating a message was dropped. It would probably be pretty useful to print the contents of the dropped message to the log as well. This way if one of the dropped messages really does break bitcoin, you can see what message caused the problem. It would also allow you to later re-create the problem by adding a filter on the incoming network stream blocking messages like the one that broke it the first time so that you can verify that you have fixed the issue later on.
If you think it is a good idea I can probably add this myself as well.
-Buck
I didn’t realize you were going to document all the intentionally undocumented commands. They’re unsupported and not intended to be used by users.
All the user-facing commands are listed in the -? help.
I wondered if they were not really meant to be public facing. I think they are useful to have documented though, at least for now. If the program accepts it as valid input it should be documented. You can either add a notice to the commands in the man-page that are experimental, or just remove them. In my opinion it makes more sense to label them experimental so people know they might change, but can use them if they need to. I would just add the following to the beginning of each of the commands in the makefile:
\fBUnsupported - Behaviour may change in future versions\fR
The \fB switches on bold text and the \fR switches back to regular. This way people can use the program to its fullest potential during the development stages. Too much documentation is never a bad thing, especially for an open source project. Since people can see the code they will find these calls anyway and use them whether you want them to or not. If they are documented and marked as volatile then people can at least make an informed choice on whether or not they want to use them.
For example, just at the moment someone in IRC is making use of the -printblock command to generate statistics about the block chain that might help us understand the program better (as in how it performs in the real world). Although the output of this command may change in the future, and therefore we shouldn’t be building complex frameworks around it, it is nice to know it exists if you need something done as a quick hack. Also because the program is open source, if someone comes to depend on a certain command line switch they can maintain it. Eventually what you thought was just a temporary debugging tool make end up being one of the most widely used switches available.
-Buck
They’re only intended for intrepid programmers who read the sourcecode.