On Saturday 19 November 2005 08:33, Mathieu Roy wrote: > Saturday 19 November, vers 0h, Tobias Toedter écrivit : > > Note that phpDocumentor does not need to be shipped with Savane, the > > resulting pages are HTML only. Furthermore, the program can generate > > PDF files, should we need that. > > You mean like > http://download.gna.org/savane/docs/developer-reference.php-frontend/ > (outdated)
Hm, that seems to do the job nicely. I wasn't aware of this. How is it
generated -- by manual runs of doxygen? If so, would there be a way to get
it updated regularly?
Concerning the comment style, how about using the following layout:
##
# This is a one line description of the function
#
# This adds some more explaining text
# And still more
function explain_me($txt)
{
[...]
}
Could you be convinced to accept this style?
> On the overall, we may include in the trunk, in doc/devel, the
> conffile needed to put up such documentation (that should be put in
> the download area), but putting generated files into the trunk would
> not be clean and useful.
Having the conffile under source control (or at least publically available
somewhere) seems like a good idea to me. I didn't meant to include
generated files in the SCM, this is never a good idea.
> > And while we're happily documenting, there's another aspect we get
> > for free: We could get rid of all those deprecated functions, which
> >
> > are nothing more than something like this:
> > > DEPRECATED
> >
> > function old_func($param)
> > {
> > new_func($param);
> > }
>
> As I said in comment of another item, many functions should have
> better name, name that says what we want do it with, not what is
> actually technically do.
> The later case should happen only when a function is only meant to do
> a technical thing but not meant for general usage all over the code.
Should we stick to the convention of using the filename (or logical package)
of the function as first word? E.g. utils_*, html_*, user_*, ...
> But I'm not very fond of the idea of this happening on the
> COOKBOOKandEXPORT branch. I would not have time to resolve merge
> conflict or to debug things others than the one being implemented.
> Well, doing it on the trunk would not be wise either..
OK. This is not a task which has to start immediately. It's surely better to
think about things first, so we get a consistent usage. That's exactly why
I started my two test balloons in utils.php, to trigger the discussion
based on a real-world example.
> Well, if you want to start doing that, and so on the current branch,
> please post task related to that and post a comment when you start
> working on an area mentioning which one (like /my or whatever). And
> please, ask me before touching include/trackers and
> include/trackers_run so we can avoid merge conflict.
Will do.
Cheers,
--
Tobias
"Only two things are infinite, the universe and human stupidity,
and I'm not sure about the former" -- Albert Einstein
pgpgsFpmcfei2.pgp
Description: PGP signature
_______________________________________________ Savane-dev mailing list [email protected] https://mail.gna.org/listinfo/savane-dev
