Re: [Patch] Whole regex refactoring and current status

[Paolo Carlini <paolo dot carlini at oracle dot com>]

Hi,

other may have different points of view...

On 08/06/2013 05:45 PM, Tim Shen wrote:
> On Tue, Aug 6, 2013 at 5:34 PM, Paolo Carlini <paolo.carlini@oracle.com> wrote:
> > That does not exactly make clearer what is missing and what already works.
> For the function _M_eat_escape(), I can finish it in hours if I've
> known what's missing and what already works. It's about reading
> standards. I added a TODO just for indicating my future(reading) work.
> Instead of documenting, I'll implement sooner.
Really, this is up to you. The point of our comments wasn't steering the 
implementation work one way or another, was instead about doucmenting 
what we are doing in a meaningful way. Frankly, that comment isn't 
serious. *Two* full lines of text, explaining what works, what doesn't, 
with a citations from the Standard would perfectly do, as far as I'm 
concerned.
> > Yeah, I agree. To be honest, adding comments isn't the point of the patch,
> > and the terse comment was already there. Still, I'm seriously concerned
> > about post-GSOC: either Tim will be able to maintain single handedly the
> > code (and likely complete it, since we are talking about a big project, eg,
> > all the various basic, extended, awk, grep and egrep variants) or we want
> > damn serious documentation everywhere... probably we want it in any case.
> So turns out it's better to add `damn serious documentation`
> everywhere. I think its OK and easy for me to maintain it after GSoC,
> but there may be unpredictable accidents.
That's great to know. But yes, documentation is badly needed.
> Should the most important documentation be implementation status? I
> think for the core part(regex_automaton and regex_executor), there's
> nothing more than classic algorithms(DFS and BFS, SSSP) and data
> structures(Graph).
I think we are back to what more or less we already discussed: a blurb 
at the beginning of each file implementing non-trivial algorithms 
explaining which algorithms are implemented, with bibliographic 
references; comments - *many* - in line in the code explaining in a 
terse but not stupid way what the next lines of code do, tricky points, 
special cases, etc; and then FIXME, TODO, again short, but not stupid, 
at least a reference to the Standard or a reference to an algorithm 
which will be implemented in that place, or a little explanation in 
plain text, two lines, but full, dense of content. Plus the status 
thing, which we already discussed lately.

This said, frankly I can't say that there are plenty of *amazing* 
examples of the above in v3, but for the blurb thing I can point you to 
stl_deque.h for example, for references to algorithms, <random>. Have a 
look to the comments in the compiler too, for inspiration.

By the way, your last patch is fine with me, I like the new *.tcc a lot. 
Just allow a day or so for further comments..

Thanks!
Paolo.