[Bug regex/11857] New: Missing documentation in regex.h

[Bug regex/11857] New: Missing documentation in regex.h

[rrt at sc3d dot org]

The attached patch addresses the following deficiencies in regex.h's documentation:

1. It mentions that re_compile-allocated pattern buffers should be freed with
regfree. (This may seem surprising, as regfree is in the POSIX API, not the GNU
API. Eric Blake, 20 Jul 10, wrote to bug-gnulib@gnu.org:

Odd or not, that is the correct usage pattern.  regfree() is the correct
way to release memory allocated by re_compile.

)

2. It explains that when using regfree, the translate member must either be NULL
or a malloced pointer. (See http://sourceware.org/bugzilla/show_bug.cgi?id=5718)

3. It adds not_bol, not_eol and newline_anchor to the list of fields that are
user-accessible after compilation (thanks to Bruno Haible for answering my
question about this on bug-gnulib 29 Jul 10).

Note that this patch only changes comments, not code.

-- 
           Summary: Missing documentation in regex.h
           Product: glibc
           Version: unspecified
            Status: NEW
          Severity: minor
          Priority: P2
         Component: regex
        AssignedTo: drepper at redhat dot com
        ReportedBy: rrt at sc3d dot org
                CC: glibc-bugs-regex at sources dot redhat dot com,glibc-
                    bugs at sources dot redhat dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug regex/11857] Missing documentation in regex.h

[rrt at sc3d dot org]

------- Additional Comments From rrt at sc3d dot org  2010-07-30 09:29 -------
Created an attachment (id=4888)
 --> (http://sourceware.org/bugzilla/attachment.cgi?id=4888&action=view)
Patch to regex.h.

Changelog for the attached patch:

2010-07-30  Reuben Thomas  <rrt@sc3d.org>

	* Update regex.h documentation to expand list of
	user-accessible fields in pattern buffers, and explain
	how to free pattern buffers initialised with
	re_compile.


-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug regex/11857] Missing documentation in regex.h

[rrt at sc3d dot org]

------- Additional Comments From rrt at sc3d dot org  2010-07-30 19:30 -------
I have found another error in the documentation in regex.h:

/* If this bit is set, then anchors do not match at newline
     characters in the string.
   If not set, then anchors do match at newlines.  */

This is the wrong way around (cf. the documentation of newline_anchor and the
relevant page in the glibc manual).

I will now update my patch to fix this problem too.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug regex/11857] Missing documentation in regex.h

[rrt at sc3d dot org]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
Attachment #4888 is|0                           |1
           obsolete|                            |


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug regex/11857] Missing documentation in regex.h

[rrt at sc3d dot org]

------- Additional Comments From rrt at sc3d dot org  2010-07-30 20:20 -------
Created an attachment (id=4889)
 --> (http://sourceware.org/bugzilla/attachment.cgi?id=4889&action=view)
Updated regex.h documentation patch

As before, but this time also fixes documentation of REG_NEWLINE.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug regex/11857] Missing documentation in regex.h

[rrt at sc3d dot org]

------- Additional Comments From rrt at sc3d dot org  2010-07-30 22:09 -------
Unfortunately, there appear to be more minor problems with the documentation. I
will update my patch once more as soon as I have had my reasoning scrutinised.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug regex/11857] Missing documentation in regex.h

[rrt at sc3d dot org]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
Attachment #4889 is|0                           |1
           obsolete|                            |


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug regex/11857] Missing documentation in regex.h

[rrt at sc3d dot org]

------- Additional Comments From rrt at sc3d dot org  2010-07-31 19:35 -------
Created an attachment (id=4890)
 --> (http://sourceware.org/bugzilla/attachment.cgi?id=4890&action=view)
Updated regex.h documentation patch

Patch with help from Eric Blake, Paolo Bonzini and Bruno Haible on bug-gnulib.
Thanks, guys!

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11857

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.