After a long hiatus, here's the next iteration of Subversion
documentation. Everything is documented except for:
- Some constants
- svn_fs_* functions
- svn_repos_* functions
- svn_import, svn_status and svn_update
The last bullet I'll try to get finished ASAP. Will it be any
trouble if
the first set of documentation is missing the first three bullet
items?
I actually haven't the foggiest what the svn_fs_* functions are
supposed
to do, so they'll take an inordinate amount of time to figure out.
There are no rules for this so you could submit just one function if
you wished. So no, it will not be any trouble.
Some points of interest in the attached tarball:
- URLs still haven't been put in global_entities file. Sorry. I'm
lazy.
This must be changed before any commit is made or really before a
true review can be performed.
- Patch for language-snippets.ent included, I needed to add some
boilerplate warning text for a bug I encountered while poking the
library
The tone of this warning makes it sound like a bug, and maybe it is,
but it could be a feature too. That and we do not document bugs.
Please rewrite it to simply report the behavior and if this behavior
changes in the future then we will document it.
- I was a bit creative in some of the examples, adding two wrapper
functions that I thought were reasonably short and added to a user's
understanding of the function. I hope they're alright
This is alright.
- In interest of keeping information centralized, I made the functions
that used certain constants point to the base ref page, and I added a
custom ID for the section I wanted an anchor for. I hope that was done
alright.
This has never been done before (that I know of) and although it's
useful I would prefer not having these hard links. We should be able
to automate the process of linking constants (livedocs) so please
instead use either <constant> or link to the constants page directly.
And overall there remains a few other notes of interest:
1. Some words (like in configure.xml) are written for today but not
tomorrow. In otherwords, the docs should stand the test of time. So
instead of "Currently, the pre-compiled DLLs..." you would write that
version 0.2... because this will be true forever. And the term "as of
0.2" is in a few places when it rarely should be. I hope this makes
sense, it should when put in the context of what is being written here.
2. Some constants in constants.xml are lowercase... is this really
correct?
3. "as of version 0.2, the Subversion extension is incomplete" this
type description is unnecessary. This is a beta extension, users know
this, but even so this will also not stand the test of time... and
it's an opinion. It's difficult to know if "as of" means 0.2+ or if
it's 0.2 and before. The phrase would mean 0.2+ elsewhere in the docs.
4. Also add .cvsignore for new extensions (see another extension for
an example)
So basically we're getting there but since this is your first commit
and we're in the "review stage" I suggest the following:
1. Create the non-function files like reference.xml (done)
2. Pick 5 functions
3. Submit for review
Submitting everything, both complete and incomplete, is too difficult
to review or understand what to review. And be sure these are ready
for commit, like using entities for links.
Regards,
Philip
