Moin,
all links on
http://meta.wikimedia.org/wiki/Source_code_documentation
are broken. Seems something moved in/from sourceforge.net :)
best wishes,
Tels
I deleted that stuff because we were running out of space and it was taking up a lot.
It could be set up elsewhere, but was anyone actually using that stuff?
Ævar Arnfjörð Bjarmason wrote:
I deleted that stuff because we were running out of space and it was taking up a lot.
It could be set up elsewhere, but was anyone actually using that stuff?
FYI, I tried running phpdoc over the current code and found it breaking the memory limit of 256 megabytes I have set on my server.
We might want to consider a new documentation parser that can handle our code. :)
-- brion vibber (brion @ pobox.com)
Brion Vibber wrote:
FYI, I tried running phpdoc over the current code and found it breaking the memory limit of 256 megabytes I have set on my server.
We might want to consider a new documentation parser that can handle our code. :)
Hello,
r13740 migrated trunk from phpdoc to doxygen, I even updated the mwdocgen.php.
The default configuration template only generates HTML output (in the same directory).
cheers,
On 4/19/06, Ashar Voultoiz hashar@altern.org wrote:
Brion Vibber wrote:
FYI, I tried running phpdoc over the current code and found it breaking the memory limit of 256 megabytes I have set on my server.
We might want to consider a new documentation parser that can handle our code. :)
r13740 migrated trunk from phpdoc to doxygen, I even updated the mwdocgen.php.
Excellent, as Brion mentions the phpdoc package is horribly written, when I was generating this documentation I was forced to add more memory by creating a virtual swap partition (dd => mkswap => swapon), which send my box into swapping hell that it couldn't get out of for the next hour or so (it's very slow even if you manage to keep it all in RAM though).
Ashar Voultoiz wrote:
Brion Vibber wrote:
FYI, I tried running phpdoc over the current code and found it breaking the memory limit of 256 megabytes I have set on my server.
We might want to consider a new documentation parser that can handle our code. :)
Hello,
r13740 migrated trunk from phpdoc to doxygen, I even updated the mwdocgen.php.
Neat! Now being autogenerated daily at http://svn.wikimedia.org/doc/
-- brion vibber (brion @ pobox.com)
Moin,
On Wednesday 19 April 2006 20:58, Brion Vibber wrote:
Ashar Voultoiz wrote:
Brion Vibber wrote:
FYI, I tried running phpdoc over the current code and found it breaking the memory limit of 256 megabytes I have set on my server.
We might want to consider a new documentation parser that can handle our code. :)
Hello,
r13740 migrated trunk from phpdoc to doxygen, I even updated the mwdocgen.php.
Neat! Now being autogenerated daily at http://svn.wikimedia.org/doc/
Cool. Although the documention is still largely, well, not usefull:
Example:
Parser::$mTitle Reimplemented in ParserXML.
Definition at line 108 of file Parser.php.
It doesn't say what it is for, or what values it could have, or whatever. Almost every member or class definition I looked at looks like this, circulare references between files but nowhere any real doc beyond "it exist and is called foo".
Since at least for members there are usually comments (like for mTitle), should't the autogenerated doc pick them up and display them somehow?
(Sorry for sounding so picky! :-)
best wishes,
Tels
On 19/04/06, Tels nospam-abuse@bloodgate.com wrote:
It doesn't say what it is for, or what values it could have, or whatever. Almost every member or class definition I looked at looks like this, circulare references between files but nowhere any real doc beyond "it exist and is called foo".
Since at least for members there are usually comments (like for mTitle), should't the autogenerated doc pick them up and display them somehow?
As Avar said in a previous message; the documentation is limited in terms of the original code; if the comments to document it were not there, then the generated documentation will be sparse.
Rob Church
Moin,
On Wednesday 19 April 2006 21:34, Rob Church wrote:
On 19/04/06, Tels nospam-abuse@bloodgate.com wrote:
It doesn't say what it is for, or what values it could have, or whatever. Almost every member or class definition I looked at looks like this, circulare references between files but nowhere any real doc beyond "it exist and is called foo".
Since at least for members there are usually comments (like for mTitle), should't the autogenerated doc pick them up and display them somehow?
As Avar said in a previous message; the documentation is limited in terms of the original code; if the comments to document it were not there, then the generated documentation will be sparse.
I _know_. :)
What I wanted to say is that the *comments* are there, but not in the proper format:
$sFoo = ''; // This variable stores a string
The comment there is ignored by the doc generator. So presumable the comments need to be reformated, or whatever (I am not familiar on how doxygen works exactly). Of course, it would be quite some work. But maybe it could be semi-automated.
Best wishes,
Tels
On 4/19/06, Rob Church robchur@gmail.com wrote:
On 19/04/06, Tels nospam-abuse@bloodgate.com wrote:
It doesn't say what it is for, or what values it could have, or whatever. Almost every member or class definition I looked at looks like this, circulare references between files but nowhere any real doc beyond "it exist and is called foo".
Since at least for members there are usually comments (like for mTitle), should't the autogenerated doc pick them up and display them somehow?
As Avar said in a previous message; the documentation is limited in terms of the original code; if the comments to document it were not there, then the generated documentation will be sparse.
In my experience, this is a good time to mention that one of the best ways to learn a codebase is to go in and document it, so if there are any wanna-be MediaWiki masters out there... :)
(It is also possible that doxygen isn't picking up the member comments, though. Running doxygen locally and consulting the log it generates should give some clues, as will making sure that the comments are formatted in a way that will get picked up, although phpDoc and dOxygen are pretty friendly towards documetation styles.)
-- Ben Garney Torque Technologies Director GarageGames.Com, Inc.
http://mail.wikipedia.org/mailman/listinfo/wikitech-l
On Wed, 19 Apr 2006 11:58:45 -0700 Brion Vibber brion@pobox.com wrote:
Ashar Voultoiz wrote:
Brion Vibber wrote:
FYI, I tried running phpdoc over the current code and found it breaking
the
memory limit of 256 megabytes I have set on my server.
We might want to consider a new documentation parser that can handle our
code. :)
Hello,
r13740 migrated trunk from phpdoc to doxygen, I even updated the mwdocgen.php.
Neat! Now being autogenerated daily at http://svn.wikimedia.org/doc/
-- brion vibber (brion @ pobox.com)
zay gezunt / kveðja / gruß / salutas / best regards
reinhardt [[user:gangleri]] irc://irc.freenode.net/mediawiki irc://irc.freenode.net/wiktionary +49-89-89670017 gangleri@torg.is skype: "irelgnag" http://easy.go.is/gangleri/ for updates see http://easy.go.is/gangleri/uppfaert/
Tels wrote:
I expected a lot more text like: what does it do?
Brion Vibber wrote:
Neat! Now being autogenerated daily at http://svn.wikimedia.org/doc/
I haven't used Doxygen with PHP, so I don't know how much it is able to extract from PHP code. However, here are some notes, based on my experience using it (a few years ago) with C code:
* There are assorted options that can be turned on.
One option I like is the one that turns on clickable (image-mapped) context diagrams. These are generated by the dot(1) program of the Graphviz suite.
The XML output option can be useful, if anyone wants to do analysis of the extracted information (I might :-).
* Although Doxygen can extract some information from the code, it really starts to shine when the programmers have added some mark-up. This consists of specially-formatted comment blocks, placed just before the code that defines data structures, functions, etc.
Here's an example:
/*! \brief Brief description. * Brief description continued. * * Detailed description starts here. */
The "\brief" tag is one of several dozen that can be used to specify particular information. Common tags include \def, \file, \fn, \param, and \var. The more information Doxygen is given, the better documentation it can produce.
* Doxygen is quite customizable. If you don't like the way the pages look, it's not that hard to change them. Of course, this will saddle you with maintenance issues when Doxygen gets updated...
* The Doxygen manual is quite extensive (132 pages) and very readable. I have also found the author to be responsive. Finally, there is an active mailing list. For more infor- mation, visit the Doxygen web site:
http://www.stack.nl/~dimitri/doxygen/
-r
Moin,
On Tuesday 18 April 2006 03:04, Ævar Arnfjörð Bjarmason wrote:
I deleted that stuff because we were running out of space and it was taking up a lot.
It could be set up elsewhere, but was anyone actually using that stuff?
Well, I tried :)
Actually, I wanted to find documentation on the Parser class, it's functions and members. However, the automatic documentation feature doesn't seem to offer much more then "this function does exist and has the following params".
I expected a lot more text like: what does it do? What are the params actually? what some possible values? etc.
So, I am not sure if the autogenerated doc is very usefull at all. It's a start, but in the end I just looked in the source whenever I wanted to see how something really works :)
best wishes,
Tels
On 4/18/06, Tels nospam-abuse@bloodgate.com wrote:
Moin, Actually, I wanted to find documentation on the Parser class, it's functions and members. However, the automatic documentation feature doesn't seem to offer much more then "this function does exist and has the following params".
I expected a lot more text like: what does it do? What are the params actually? what some possible values? etc.
So, I am not sure if the autogenerated doc is very usefull at all. It's a start, but in the end I just looked in the source whenever I wanted to see how something really works :)
Automatically generated documentation will only ever be as good as the source code (or other data) it's generated from. So this is a symptom of classes and other interfaces not being documented well enough, not of the documentation system as such.
On 19/04/06, Ævar Arnfjörð Bjarmason avarab@gmail.com wrote:
On 4/18/06, Tels nospam-abuse@bloodgate.com wrote:
Moin, Actually, I wanted to find documentation on the Parser class, it's functions and members. However, the automatic documentation feature doesn't seem to offer much more then "this function does exist and has the following params".
I expected a lot more text like: what does it do? What are the params actually? what some possible values? etc.
So, I am not sure if the autogenerated doc is very usefull at all. It's a start, but in the end I just looked in the source whenever I wanted to see how something really works :)
Automatically generated documentation will only ever be as good as the source code (or other data) it's generated from. So this is a symptom of classes and other interfaces not being documented well enough, not of the documentation system as such.
Got it in one. If the comments are wrong, then the documentation will be, too.
Rob Church
wikitech-l@lists.wikimedia.org