You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by rb...@covalent.net on 2000/08/17 18:07:55 UTC
Removing apidoc from 2.0
If nobody complains, I would like to remove the apidoc directory from the
2.0-httpd-docs tree. Once that is done, I will add instructions for
generating the docs using ScanDoc in the "Rolling a release" instructions
on dev.apache.org. This will leave us with a fully documented API. It
could probably use some work, but every function is documented.
I would like to do this before the 6th alpha, which is rolled tomorrow.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Removing apidoc from 2.0
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
rbb@covalent.net wrote:
>
> Whooops.. I meant to say that, yes +1 for option #3
Right-ho. In the absence of any other opinions on this,
and since it hadn't been touched at all since its creation,
I have zapped the httpd-docs-2.0/apidoc/ directory tree.
I have replaced it with the inclusion of submodules, so
a checkout of httpd-docs-2.0 will now give you
httpd-docs-2.0/
htdocs/
...
apidoc/
httpd/ # from apache-2.0/src/include/
apr/ # from apache-2.0/src/lib/apr/include/
os/ # from apache-2.0/src/os/unix/
The only two things remaining are to make sure those directories
are owned by the right group (one that both docco people and coders
are in), and verifying how the karma check deals with the situation
and making sure it works correctly. I'm working with Brian on
these.
Using CVS magic to include the docs with the sources appears to be
not-so-good for both 1.3 and 2.0 because of the Attic contents.
I'll probably be backing that change out very soon, so we'll be
going back to having to check out both source and docs. cvs update
should work better after that reversion, too.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Removing apidoc from 2.0
Posted by rb...@covalent.net.
>
> > The reason for src/os/unix, is that all platforms must implement
> > os.h, which has to have a core set of functions, and then platforms
> > may implement more than that core. Because I didn't want to
> > document the same stuff multiple times, I chose to doc unix/os.h
> > with the assumption that those files will all likely be merged
> > and moved to the src/include directory relatively soon.
>
> Does that mean you're +1 for #3?
Whooops.. I meant to say that, yes +1 for option #3
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Removing apidoc from 2.0
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
rbb@covalent.net wrote:
>
> In that case, it has actually shown a problem with splitting the
> tree.
Not really. Since we had NO documentation on the API when it was
split, that directory just turned out to be a no-op. A road
not taken.
> BTW, policing this stuff does work. I know it works because I got
> the idea from Rasmus. Accoring to him, he polices stuff that is
> committed to PHP to ensure that it has corresponding docs, and as
> you point out below Ken, PHP has been wildly successful with their
> documentation. :-)
I didn't say policing *can't* work, I said it *won't*. It *can*,
in the right circumstances. I personally don't think it will work
for Apache the way it has for PHP because the models and community
mindsets are too different.
> The reason for src/os/unix, is that all platforms must implement
> os.h, which has to have a core set of functions, and then platforms
> may implement more than that core. Because I didn't want to
> document the same stuff multiple times, I chose to doc unix/os.h
> with the assumption that those files will all likely be merged
> and moved to the src/include directory relatively soon.
Does that mean you're +1 for #3?
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Removing apidoc from 2.0
Posted by rb...@covalent.net.
> That's right; I said as much when I created the stuff. Which was
> about a week before you switched to ScanDoc, so you weren't
> all that far along with the API docco at that point. I have no
> problem with nuking the current contents of httpd-docs-2.0/apidoc/;
> my concern is: with what do we replace it?
In that case, it has actually shown a problem with splitting the tree. I
update my trees pretty much everyday to make sure I am always operating on
head. I then use the trees and the supplied docs for my testing. I
brought this up three days ago, because that was the first time I noticed
the apidoc directory. The simple fact that it took me that long to find
it is not good. I think it may be because I wasn't updating that
directory automatically, and I never did a cvs co on httpd-docs-20, which
is my fault, but it is still uncool.
BTW, policing this stuff does work. I know it works because I got the
idea from Rasmus. Accoring to him, he polices stuff that is committed to
PHP to ensure that it has corresponding docs, and as you point out below
Ken, PHP has been wildly successful with their documentation. :-)
> Personally, I think #3 is the best bet. A search of the include files
> for '@deffunc' reveals that it only occurs in src/include, src/os/unix,
> and src/lib/apr/include. (I'm assuming that only those directories
> that mention @deffunc contain real ScanDoc stuff.) I'm a little bit
> concerned about that src/os/unix instance; either ther should be
> corresponding src/os/* entries for the other platforms, or its docco
> should be merged into one of the oter locations.
The reason for src/os/unix, is that all platforms must implement os.h,
which has to have a core set of functions, and then platforms may
implement more than that core. Because I didn't want to document the same
stuff multiple times, I chose to doc unix/os.h with the assumption that
those files will all likely be merged and moved to the src/include
directory relatively soon.
> As for the security issue.. if a documentor breaks something, we
> restore it and take away access. Big deal; that's why we have
> CVS.
>
> Curiously enough, the PHP documentation project, which is hugely
> successful, has the docco completely divorced from the source.
> (I think. Rasmus? Sascha?) But I think they may be moving toward
> an embedded solution at some point, when they may encounter the
> same issue we have now.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Removing apidoc from 2.0
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
rbb@covalent.net wrote:
>
> That is an impossible problem to solve.
No it isn't. It may be that we don't like any of the solutions,
but it's hardly impossible.
> Currently the docs we have are incomplete and they may actually be
> wrong in some places, because as far as I know, they are an exact
> copy from 1.3.
That's right; I said as much when I created the stuff. Which was
about a week before you switched to ScanDoc, so you weren't
all that far along with the API docco at that point. I have no
problem with nuking the current contents of httpd-docs-2.0/apidoc/;
my concern is: with what do we replace it?
These would seem to be our choices:
1. Leave things the way they are.
2. Move the ScanDoc bits out of the .h files into separate files
under httpd-docs-2.0.
3. Construct the httpd-docs-2.0/apidoc/ module from inclusions of
the modules/directories where the include files containing ScanDoc
bit are located.
[1] sucks because it's a step back to 1.3.11 and earlier; the only
people who can document stuff are the coders, who don't have the
most impressive history. (And playing cop won't work very well
either, Ryan. :-)
[2] sucks because the function prototypes are an integral part of
ScanDoc's input. (Well, maybe not, since we need to @deffunc
everything that has API_* in it. But that might be fixed for
ScanDoc, so we should assume the reason applies.) This would
reintroduce the problem of separating the docco from the code,
with all the synchronisation issues that entails.
[3] could possibly suck because in order to allow documenters to
work on the docco we'd need to grant them access to the include
files.
Personally, I think #3 is the best bet. A search of the include files
for '@deffunc' reveals that it only occurs in src/include, src/os/unix,
and src/lib/apr/include. (I'm assuming that only those directories
that mention @deffunc contain real ScanDoc stuff.) I'm a little bit
concerned about that src/os/unix instance; either ther should be
corresponding src/os/* entries for the other platforms, or its docco
should be merged into one of the oter locations.
As for the security issue.. if a documentor breaks something, we
restore it and take away access. Big deal; that's why we have
CVS.
Curiously enough, the PHP documentation project, which is hugely
successful, has the docco completely divorced from the source.
(I think. Rasmus? Sascha?) But I think they may be moving toward
an embedded solution at some point, when they may encounter the
same issue we have now.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Removing apidoc from 2.0
Posted by rb...@covalent.net.
On Thu, 17 Aug 2000, Rodent of Unusual Size wrote:
> rbb@covalent.net wrote:
> >
> > If nobody complains, I would like to remove the apidoc directory
> > from the 2.0-httpd-docs tree.
>
> The problem with this is that it defeats the purpose of enabling
> non-coders to work on the documentation. The way things are now
> in 2.0, only someone with commit access to the source tree can
> do diddly with the docco.
>
> -1 until we figure out a solution to that.
That is an impossible problem to solve. Currently the docs we have are
incomplete and they may actually be wrong in some places, because as far
as I know, they are an exact copy from 1.3. The docs generated by ScanDoc
are complete and correct because they were written explicitly for 2.0. A
bigf portion of the API changed. The only way to commit a change to the
API docs, is to have access to the source, that is true. The other
option is to keep a copy of the docs outside the source tree, but that too
is sub-optimal, because then the docs aren't changed with the code. This
is one of the problems, and one of the reasons that we have never had a
completely documented API. I really think having a documented API is
worth forcing people to work on it within the code.
> > Once that is done, I will add instructions for generating the
> > docs using ScanDoc in the "Rolling a release" instructions
> > on dev.apache.org.
>
> And where do/should they go on the Apache site? Another question
> to be answered before charging ahead and changing the current
> suboptimal situation.
Where are the current docs for the API? Make that page a page that simply
branches to two locations, 1.3 and 2.0 docs.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Removing apidoc from 2.0
Posted by rb...@covalent.net.
On Thu, 17 Aug 2000, Rodent of Unusual Size wrote:
> Marc Slemko wrote:
> >
> > As I have said numerous times in the past, there is absolutely no need
> > to put docs into a separate top level directory in the CVS repository
> > to allow differing commit access to them.
>
> That remark doesn't apply to the 2.0 situation, because the 2.0
> API docs are *in* the source, not in separate files as in 1.3.
> So you can't grant access to the docs without also granting access
> to the source -- because they're the same.
That is a bit of a misnomer. The docs are in the headers, which are a
kind of source file, yes. But, the docs are all located in two or three
directories. src/include apr/src/include src/os/unix. That last one is
because of the os.h files every OS must implement. 99% of the problem
could be solved by opening access to src/include and apr/src/include.
The other solution, would be for somebody to write a new template file for
ScanDoc. That template would generate XML from the ScanDoc comments. We
could store those anywhere. Then, we would need scripts to incorporate
the changes to the XML back into the headers, but I think that could be
managed.
The fact remains that we have two sets of docs. One is complete and
ready to use, but it requires people have access to the include files in
order to modify them. The other is in completely dissparate files from
the headers, but are incomplete.
I would rather open up the headers to more people, and have complete
headers. I think we have enough competant perl hackers that we could have
the XML template quickly, and a tool to merge the doc changes back in
quickly. The doc merge script could be run as a part of the CVS commit
obviously.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Removing apidoc from 2.0
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Marc Slemko wrote:
>
> As I have said numerous times in the past, there is absolutely no need
> to put docs into a separate top level directory in the CVS repository
> to allow differing commit access to them.
That remark doesn't apply to the 2.0 situation, because the 2.0
API docs are *in* the source, not in separate files as in 1.3.
So you can't grant access to the docs without also granting access
to the source -- because they're the same.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Removing apidoc from 2.0
Posted by Ask Bjoern Hansen <as...@valueclick.com>.
On Thu, 17 Aug 2000, Marc Slemko wrote:
[...]
> If you want to allow a different set of users to commit to a certain
> subdirectory, simply make all the files in that subdirectory owned
> by a separate group. End of story. There is nothing magic as far as
> permissions go WRT what level within the CVS repository the directory
> is at.
and the give-karma thingy we use works on a directory basis too,
IIRC.
- ask
--
ask bjoern hansen - <http://ask.netcetera.dk/>
more than 70M impressions per day, <http://valueclick.com>
Re: Removing apidoc from 2.0
Posted by Marc Slemko <ma...@znep.com>.
On Thu, 17 Aug 2000, Rodent of Unusual Size wrote:
> rbb@covalent.net wrote:
> >
> > If nobody complains, I would like to remove the apidoc directory
> > from the 2.0-httpd-docs tree.
>
> The problem with this is that it defeats the purpose of enabling
> non-coders to work on the documentation. The way things are now
> in 2.0, only someone with commit access to the source tree can
> do diddly with the docco.
>
> -1 until we figure out a solution to that.
As I have said numerous times in the past, there is absolutely no need
to put docs into a separate top level directory in the CVS repository
to allow differing commit access to them.
If you want to allow a different set of users to commit to a certain
subdirectory, simply make all the files in that subdirectory owned
by a separate group. End of story. There is nothing magic as far as
permissions go WRT what level within the CVS repository the directory
is at.
Re: Removing apidoc from 2.0
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
rbb@covalent.net wrote:
>
> If nobody complains, I would like to remove the apidoc directory
> from the 2.0-httpd-docs tree.
The problem with this is that it defeats the purpose of enabling
non-coders to work on the documentation. The way things are now
in 2.0, only someone with commit access to the source tree can
do diddly with the docco.
-1 until we figure out a solution to that.
> Once that is done, I will add instructions for generating the
> docs using ScanDoc in the "Rolling a release" instructions
> on dev.apache.org.
And where do/should they go on the Apache site? Another question
to be answered before charging ahead and changing the current
suboptimal situation.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>