You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Branko Čibej <br...@xbc.nu> on 2002/12/03 23:24:36 UTC
API documentation [was: Re: Problem with python swig example - geturl.py]
Greg Stein wrote:
>I think we would want to write a little script to extract the API from our
>header files (there is a pretty standard format). We could possibly switch
>to doxygen or something, too.
>
>
+1! This is something I'd been thinking about on and off for a while.
Our public APIs are moderately well documented, but looking into headers
can be a bit of a pain sometimes. I say let's use Doxygen for all our
source docs. Starting with just the public headers in subversion/include
shouldn't be that hard.
--
Brane Čibej <br...@xbc.nu> http://www.xbc.nu/brane/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Peter Davis <pe...@pdavis.cx> writes:
> I'm not opposed to doing that, but I'm just not thrilled that File Sharing is
> really for downloading files instead of normal browsing. With Konqueror at
> least, HTML files show up in a separate browser window with no forward/back
> buttons or menu. I guess File Sharing wouldn't be toooo bad.
>
> Other options are to post a tarball or .zip file containing all the docs,
> which still isn't browseable, but probably should be done anyway for offline
> browsing.
Well, if you want to post them to File Sharing right now, go for it.
The auto-updated browseable web site is not on our backmost burner at
the moment, but not the frontmost either... :-)
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Peter Davis <pe...@pdavis.cx>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Wednesday 04 December 2002 11:36, Karl Fogel wrote:
> Oh, I was asking about uploading to a File Sharing area, actually.
I'm not opposed to doing that, but I'm just not thrilled that File Sharing is
really for downloading files instead of normal browsing. With Konqueror at
least, HTML files show up in a separate browser window with no forward/back
buttons or menu. I guess File Sharing wouldn't be toooo bad.
Other options are to post a tarball or .zip file containing all the docs,
which still isn't browseable, but probably should be done anyway for offline
browsing.
- --
Peter Davis
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)
iD8DBQE97mY3hDAgUT1yirARAuttAJ0aP9+Gsrp90suNwlRZM9RRI5wFNACdHxEn
AdRTCA723YQdsCzJBqD98T8=
=J4J+
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Peter Davis <pe...@pdavis.cx> writes:
> Sure, it should be easy enough to generate the HTML after API changes. I
> guess all I would need is [S]FTP and/or SSH access to the working copy from
> which the website is hosted.
Oh, I was asking about uploading to a File Sharing area, actually.
Updating a live website this is actually a little more complex than
one might think, as we'd probably have to host the doxgenated website
on svn.collab.net and redirect to it from subversion.tigris.org (which
is an svn working copy, but not one that a post-commit script can
easily affect). This is because our svn server is not on
subversion.tigris.org, but on svn.collab.net.
We'll investigate, and only take you up on your offer if it's not easy
to Just Do It. Thanks!
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Peter Davis <pe...@pdavis.cx>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Wednesday 04 December 2002 06:36, Karl Fogel wrote:
> Is that a volunteer I hear?
Sure, it should be easy enough to generate the HTML after API changes. I
guess all I would need is [S]FTP and/or SSH access to the working copy from
which the website is hosted.
I would consider posting to the File Sharing section, but downloading HTML
files from there just isn't really browseable. If the File Sharing servlet
could be modified to not hide the browser toolbar (forward/back buttons) and
to not open HTML in a separate window.
The API should also have some sort of human-intuitive URL, such as
http://subversion.tigris.org/api/0.16/ and
http://subversion.tirgris.org/api/current/ (redirect), which File Sharing
doesn't provide without an external redirect.
Is the website run directly out of a Subversion WC, or is it out of CVS like
other tigris.org sites?
- --
Peter Davis
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)
iD8DBQE97l+whDAgUT1yirARAiGKAJ4rOClx2pRHoYqjeh4hsha105/uEgCdFu87
e+BXgEosrDx1TIX/DZ+kmcs=
=wCae
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Peter Davis <pe...@pdavis.cx> writes:
> Not that any of this is too hard or tedious to do (far from it), but
> are there plans to occasionally post online copies to the web site
> (just as there are prebuilt copies of the book and other docs)?
Is that a volunteer I hear?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
"Mats Nilsson" <ma...@xware.se> writes:
> Or regularly commit the resulting files to some part of the svn
> repository to make them browseable at svn.collab.net. ;-)
No, since they're generated files.
It would be nice to have them browseable from the web site, of course.
A way to achieve that is to have commits update a live working copy
and run doxygen there. Just no need to commit generated files.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
RE: API documentation
Posted by Mats Nilsson <ma...@xware.se>.
> From: pdavis152@attbi.com [mailto:pdavis152@attbi.com] On Behalf Of
Peter Davis
> Not that any of this is too hard or tedious to do (far from it), but
are there
> plans to occasionally post online copies to the web site (just as
there are
> prebuilt copies of the book and other docs)?
Or regularly commit the resulting files to some part of the svn
repository to make them browseable at svn.collab.net. ;-)
Mats
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Peter Davis <pe...@pdavis.cx>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Tuesday 03 December 2002 18:59, Branko Čibej wrote:
> To generate the documentation, run
>
> $ doxygen doc/doxygen.donf
>
> from the top of the source tree. That'll create HTML documentation of
> the public API in doc/doxygen/html.
Not that any of this is too hard or tedious to do (far from it), but are there
plans to occasionally post online copies to the web site (just as there are
prebuilt copies of the book and other docs)?
- --
Peter Davis
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)
iD8DBQE97XOChDAgUT1yirARAuDvAJ9R6x+FeFSSy5iQO1SCfGQtEcxZkwCfTWiy
ILpMDsgRZLuhoiQe0+i6OXM=
=LDoW
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
Karl Fogel wrote:
>Ben Collins-Sussman <su...@collab.net> writes:
>
>
>>All we need now is a volunteer to go through our public header files
>>and convert CAPITALIZED arguments into @a arguments.
>>
>>
>
>Or an organized effort, divided among many people...
>
>But first, is there a volunteer who wants to take this on?
>
>
i don't have anything better to do tonight...
if nobody else jumps up with patches before then, i'll start converting
things over.
-garrett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Ben Collins-Sussman <su...@collab.net> writes:
> All we need now is a volunteer to go through our public header files
> and convert CAPITALIZED arguments into @a arguments.
Or an organized effort, divided among many people...
But first, is there a volunteer who wants to take this on?
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Ben Collins-Sussman <su...@collab.net>.
Branko Čibej <br...@xbc.nu> writes:
> There ya go, r3978 and r3979. To generate the documentation, run
>
> $ doxygen doc/doxygen.donf
>
Oooh, purty.
I had to build /usr/ports/devel/doxygen, which in turn decided to
build all of QT as a dependency (!!!), but still, relatively painless.
All we need now is a volunteer to go through our public header files
and convert CAPITALIZED arguments into @a arguments.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation
Posted by Branko Čibej <br...@xbc.nu>.
Karl Fogel wrote:
>>The point is, though, that Doxygen generates superb html docs, and this
>>is something we'll need before 1.0.
>>
>>
>
>Okay, let's go for it.
>
>If you can do a few doc strings right away, then the rest of us can
>probably starting tweaking stuff as we go (no need to lay this burden
>on just one person).
>
>
There ya go, r3978 and r3979. To generate the documentation, run
$ doxygen doc/doxygen.donf
from the top of the source tree. That'll create HTML documentation of
the public API in doc/doxygen/html. Note: no make targets for this yet,
as I couldn't be bothered to make it work for objdir != srcdir builds yet.
I've added minimal annotations subversion/include/svn_time.h.
--
Brane Čibej <br...@xbc.nu> http://www.xbc.nu/brane/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation [was: Re: Problem with python swig example - geturl.py]
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Branko Čibej <br...@xbc.nu> writes:
> Ah, but you see, Doxygen is extremely flexible and you can make the
> markup practically invisible.
Ah, okay, +1 then.
> >(On the other, Doxygen might be easier if we continue to put the param
> >names in all-caps.)
>
> Blech. That all-caps stuff is yuck anyway. :-)
> Would you accept appropriate font-lock highlighting for the Doxygen markup?
Well, I suspect most people are in your camp and never liked the
all-caps style anyway; assuming that's ture, let's get rid of it.
I'll learn to read whatever we come up with :-). Emacs highlighting
would be a nice replacement, but not necessary.
> The point is, though, that Doxygen generates superb html docs, and this
> is something we'll need before 1.0.
Okay, let's go for it.
If you can do a few doc strings right away, then the rest of us can
probably starting tweaking stuff as we go (no need to lay this burden
on just one person).
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation [was: Re: Problem with python swig example
- geturl.py]
Posted by Branko Čibej <br...@xbc.nu>.
Karl Fogel wrote:
>Branko Čibej <br...@xbc.nu> writes:
>
>
>>+1! This is something I'd been thinking about on and off for a while.
>>Our public APIs are moderately well documented, but looking into headers
>>can be a bit of a pain sometimes. I say let's use Doxygen for all our
>>source docs. Starting with just the public headers in subversion/include
>>shouldn't be that hard.
>>
>>
>
>Isn't Doxygen format the one used in APR?
>
>Personally, I find that format much less readable in the sources.
>Maybe it produces good printed docs and html, but the downside is
>there's this markup all over the source files... And the source files
>is what most developers read on a daily basis, no?
>
Ah, but you see, Doxygen is extremely flexible and you can make the
markup practically invisible.
>(On the other, Doxygen might be easier if we continue to put the param
>names in all-caps.)
>
Blech. That all-caps stuff is yuck anyway. :-)
Would you accept appropriate font-lock highlighting for the Doxygen markup?
The point is, though, that Doxygen generates superb html docs, and this
is something we'll need before 1.0.
--
Brane Čibej <br...@xbc.nu> http://www.xbc.nu/brane/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API documentation [was: Re: Problem with python swig example - geturl.py]
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Branko Čibej <br...@xbc.nu> writes:
> +1! This is something I'd been thinking about on and off for a while.
> Our public APIs are moderately well documented, but looking into headers
> can be a bit of a pain sometimes. I say let's use Doxygen for all our
> source docs. Starting with just the public headers in subversion/include
> shouldn't be that hard.
Isn't Doxygen format the one used in APR?
Personally, I find that format much less readable in the sources.
Maybe it produces good printed docs and html, but the downside is
there's this markup all over the source files... And the source files
is what most developers read on a daily basis, no?
(On the other, Doxygen might be easier if we continue to put the param
names in all-caps.)
In any case, this should be a majority rules decision among the
developers. I'm not vetoing, just explaining my preference. I like
the status quo, YMMV :-).
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org