From: Yann Dirson <ydirson@altern.org>
To: GIT list <git@vger.kernel.org>
Subject: Improving git-svn documentation
Date: Wed, 17 Jun 2009 22:18:51 +0200 [thread overview]
Message-ID: <20090617201851.GA6123@nan92-1-81-57-214-146.fbx.proxad.net> (raw)
While diving into the git-svn code, I realized that many things could
be done to make it more documented/understundable. I need to get more
understanding of it, so I'd like to improve this state of things. But
first, I'd like to be sure there is a consensus on what is a good idea
to do, since that could easily turn up into a lot of textual change.
- (on the user doc side of things) some options appear not to be
documented (I spotted --parent for 'clone' and --revision for
'dcommit'). But looking at where to document them, I found it not
always easy, since some options are documented together with the
command they modify, some others in the "options" section (even when
they are documented as applying to a single command, like --shared
or --stdin). This IMHO leads to confusion for the user looking for
information, as well as to the reviewer trying to check that nothing
was forgotten. I would rather make that only very commons are
described in a common "options" section, and that all commands using
them explicitely say so in their descriptions (with xref).
- (on the code side of things) git-svn.perl weights more than 5500
lines, most classes functions and methods severely lack
documentation, and some extensively-used variable names are so short
they make the code harder to grasp
Eg. $gs to refer to an instance of the Git::SVN class, which I would
suggest to change to something like $gsrepo, while at the same time
renaming Git::SVN to eg. Git::SVN::Repository - which would make it
much easier for a newcomer to grasp what this is supposed to
represent - supposing, that is, that my understunding of this part
is accurate enough, which it is probably not after spending many
hours in there :)
As to the size of the file, it seems natural to me to split the
classes into their own files. That would still let git-svn.perl and
the Git::SVN class to be 1500-lines tall, the largest others
achieving around 500 lines. That should be much more manageable
pieces, and would require some refactoring wrt a couple of global
variables used throughout the script; which, incidentally, could
make it much easier to simultanously look at several git-svn
repositories (for my work on mapping externals to submodules), and
to allow reusing the existing code, eg. as a git-vcs backend.
How are you people feeling about this rough plans ?
--
Yann
next reply other threads:[~2009-06-17 20:19 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2009-06-17 20:18 Yann Dirson [this message]
2009-06-17 22:04 ` Improving git-svn documentation Marc Branchaud
2009-06-21 22:48 ` [WIP PATCH 0/2] Some documentation improvements for git-svn Yann Dirson
2009-06-21 22:48 ` [PATCH 1/2] git-svn: add some in-code documentation (options-related) Yann Dirson
2009-06-21 22:48 ` [PATCH 2/2] git-svn user documentation update Yann Dirson
2009-06-21 23:48 ` [PATCH 1/2] git-svn: add some in-code documentation (options-related) Junio C Hamano
2009-06-22 19:12 ` Yann Dirson
2009-06-25 8:47 ` Improving git-svn documentation Eric Wong
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20090617201851.GA6123@nan92-1-81-57-214-146.fbx.proxad.net \
--to=ydirson@altern.org \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.