Saturday 19 November, vers 16h, Tobias Toedter dactylographia :
>
> 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?
The doxygen configuration file is into doc/devel
We could indeed set up on a machine an automated run. But in the
meantime, any savane developer can update it.
> 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?
Yes. That's fine for me, that would be nice.
> > 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.
The doxygen conffile should be in doc/devel. It probably should be
updated, as path may have changed.
> > > 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_*, ...
Yes, we should, but for functions of heavy usage, we can accept an
alias that miss the "utils_" part, to keep the code easy to read.
> > 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.
Thanks :)
Regards,
--
Mathieu Roy
+---------------------------------------------------------------------+
| General Homepage: http://yeupou.coleumes.org/ |
| Computing Homepage: http://alberich.coleumes.org/ |
| Not a native english speaker: |
| http://stock.coleumes.org/doc.php?i=/misc-files/flawed-english |
+---------------------------------------------------------------------+
_______________________________________________
Savane-dev mailing list
[email protected]
https://mail.gna.org/listinfo/savane-dev
