Clean up ptid.h/ptid.c.

The ptid_t contructors, accessors and predicates are documented in
_three_ places, and each place uses a different wording.

E.g, the descriptions in the .c file of the new ptid_lwp_p, ptid_tid_p
weren't updated in the final revision like the descriptions in the .h
file were.  Clearly, switching to a style that has a single central
description avoids such issues.

Worse, some of the existing descriptions are plain wrong, such as:

  /* Attempt to find and return an existing ptid with the given PID, LWP,
     and TID components.  If none exists, create a new one and return
     that.  */
  ptid_t ptid_build (int pid, long lwp, long tid);

The function does nothing that complicated.  It's just a simple
constructor.

So this gets rid of all the unnecessary descriptions, leaving only the
ones near the function declarations in the header file, and
fixes/clarifies those that remain.

gdb/
2013-10-04  Pedro Alves  <palves@redhat.com>

	* common/ptid.c (null_ptid, minus_one_ptid, ptid_build)
	(pid_to_ptid, ptid_get_pid, ptid_get_lwp, ptid_get_tid)
	(ptid_equal, ptid_is_pid, ptid_lwp_p, ptid_tid_p): Replace
	describing comments with references to ptid.h.
	* common/ptid.h: Remove intro description of constructors,
	accessors and predicates.
	(struct ptid): Reformat.
	(minus_one_ptid, ptid_build, pid_to_ptid, ptid_get_pid)
	(ptid_get_lwp, ptid_get_tid, ptid_equal, ptid_is_pid): Change
	describing comments.

3 files changed, 50 insertions, 49 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index af60b57..751f3d9 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,16 @@
+2013-10-04  Pedro Alves  <palves@redhat.com>
+
+	* common/ptid.c (null_ptid, minus_one_ptid, ptid_build)
+	(pid_to_ptid, ptid_get_pid, ptid_get_lwp, ptid_get_tid)
+	(ptid_equal, ptid_is_pid, ptid_lwp_p, ptid_tid_p): Replace
+	describing comments with references to ptid.h.
+	* common/ptid.h: Remove intro description of constructors,
+	accessors and predicates.
+	(struct ptid): Reformat.
+	(minus_one_ptid, ptid_build, pid_to_ptid, ptid_get_pid)
+	(ptid_get_lwp, ptid_get_tid, ptid_equal, ptid_is_pid): Change
+	describing comments.
+
 2013-10-04  Joel Brobecker  <brobecker@adacore.com>
 
 	* aix-thread.c (sync_threadlists): Add missing ')' in call
diff --git a/gdb/common/ptid.c b/gdb/common/ptid.c
index e8d25c0..d7780d3 100644
--- a/gdb/common/ptid.c
+++ b/gdb/common/ptid.c
@@ -19,11 +19,12 @@
 
 #include "ptid.h"
 
-/* Oft used ptids */
+/* See ptid.h for these.  */
+
 ptid_t null_ptid = { 0, 0, 0 };
 ptid_t minus_one_ptid = { -1, 0, 0 };
 
-/* Create a ptid given the necessary PID, LWP, and TID components.  */
+/* See ptid.h.  */
 
 ptid_t
 ptid_build (int pid, long lwp, long tid)
@@ -36,7 +37,7 @@ ptid_build (int pid, long lwp, long tid)
   return ptid;
 }
 
-/* Create a ptid from just a pid.  */
+/* See ptid.h.  */
 
 ptid_t
 pid_to_ptid (int pid)
@@ -44,7 +45,7 @@ pid_to_ptid (int pid)
   return ptid_build (pid, 0, 0);
 }
 
-/* Fetch the pid (process id) component from a ptid.  */
+/* See ptid.h.  */
 
 int
 ptid_get_pid (ptid_t ptid)
@@ -52,7 +53,7 @@ ptid_get_pid (ptid_t ptid)
   return ptid.pid;
 }
 
-/* Fetch the lwp (lightweight process) component from a ptid.  */
+/* See ptid.h.  */
 
 long
 ptid_get_lwp (ptid_t ptid)
@@ -60,7 +61,7 @@ ptid_get_lwp (ptid_t ptid)
   return ptid.lwp;
 }
 
-/* Fetch the tid (thread id) component from a ptid.  */
+/* See ptid.h.  */
 
 long
 ptid_get_tid (ptid_t ptid)
@@ -68,7 +69,7 @@ ptid_get_tid (ptid_t ptid)
   return ptid.tid;
 }
 
-/* ptid_equal() is used to test equality of two ptids.  */
+/* See ptid.h.  */
 
 int
 ptid_equal (ptid_t ptid1, ptid_t ptid2)
@@ -78,7 +79,7 @@ ptid_equal (ptid_t ptid1, ptid_t ptid2)
 	  && ptid1.tid == ptid2.tid);
 }
 
-/* Returns true if PTID represents a process.  */
+/* See ptid.h.  */
 
 int
 ptid_is_pid (ptid_t ptid)
@@ -90,7 +91,7 @@ ptid_is_pid (ptid_t ptid)
   return (ptid_get_lwp (ptid) == 0 && ptid_get_tid (ptid) == 0);
 }
 
-/* Returns true if PTID represents a lwp.  */
+/* See ptid.h.  */
 
 int
 ptid_lwp_p (ptid_t ptid)
@@ -102,7 +103,7 @@ ptid_lwp_p (ptid_t ptid)
   return (ptid_get_lwp (ptid) != 0);
 }
 
-/* Returns true if PTID represents a tid.  */
+/* See ptid.h.  */
 
 int
 ptid_tid_p (ptid_t ptid)
diff --git a/gdb/common/ptid.h b/gdb/common/ptid.h
index 1326506..2a31a1c 100644
--- a/gdb/common/ptid.h
+++ b/gdb/common/ptid.h
@@ -20,69 +20,56 @@
 #ifndef PTID_H
 #define PTID_H
 
-/* The ptid struct is a collection of the various "ids" necessary
-   for identifying the inferior.  This consists of the process id
-   (pid), thread id (tid), and other fields necessary for uniquely
-   identifying the inferior process/thread being debugged.  When
-   manipulating ptids, the constructors, accessors, and predicates
-   declared in this file should be used.  These are as follows:
-
-      ptid_build	- Make a new ptid from a pid, lwp, and tid.
-      pid_to_ptid	- Make a new ptid from just a pid.
-      ptid_get_pid	- Fetch the pid component of a ptid.
-      ptid_get_lwp	- Fetch the lwp component of a ptid.
-      ptid_get_tid	- Fetch the tid component of a ptid.
-      ptid_equal	- Test to see if two ptids are equal.
-      ptid_is_pid	- Test if a ptid is of the form (pid, 0, 0).
-      ptid_lwp_p	- Test if a ptid's lwp component is non-zero.
-      ptid_tid_p	- Test if a ptid's tid component is non-zero.
-
-   Please do NOT access the struct ptid members directly (except, of
-   course, in the implementation of the above ptid manipulation
-   functions).  */
+/* The ptid struct is a collection of the various "ids" necessary for
+   identifying the inferior process/thread being debugged.  This
+   consists of the process id (pid), lightweight process id (lwp) and
+   thread id (tid).  When manipulating ptids, the constructors,
+   accessors, and predicates declared in this file should be used.  Do
+   NOT access the struct ptid members directly.  */
 
 struct ptid
-  {
-    /* Process id */
-    int pid;
+{
+  /* Process id.  */
+  int pid;
 
-    /* Lightweight process id */
-    long lwp;
+  /* Lightweight process id.  */
+  long lwp;
 
-    /* Thread id */
-    long tid;
-  };
+  /* Thread id.  */
+  long tid;
+};
 
 typedef struct ptid ptid_t;
 
 /* The null or zero ptid, often used to indicate no process. */
 extern ptid_t null_ptid;
 
-/* The -1 ptid, often used to indicate either an error condition
+/* The (-1,0,0) ptid, often used to indicate either an error condition
    or a "don't care" condition, i.e, "run all threads."  */
 extern ptid_t minus_one_ptid;
 
-/* Attempt to find and return an existing ptid with the given PID, LWP,
-   and TID components.  If none exists, create a new one and return
-   that.  */
+/* Make a ptid given the necessary PID, LWP, and TID components.  */
 ptid_t ptid_build (int pid, long lwp, long tid);
 
-/* Find/Create a ptid from just a pid. */
+/* Make a new ptid from just a pid.  This ptid is usually used to
+   represent a whole process, including all its lwps/threads.  */
 ptid_t pid_to_ptid (int pid);
 
-/* Fetch the pid (process id) component from a ptid. */
+/* Fetch the pid (process id) component from a ptid.  */
 int ptid_get_pid (ptid_t ptid);
 
-/* Fetch the lwp (lightweight process) component from a ptid. */
+/* Fetch the lwp (lightweight process) component from a ptid.  */
 long ptid_get_lwp (ptid_t ptid);
 
-/* Fetch the tid (thread id) component from a ptid. */
+/* Fetch the tid (thread id) component from a ptid.  */
 long ptid_get_tid (ptid_t ptid);
 
-/* Compare two ptids to see if they are equal */
-int ptid_equal (ptid_t p1, ptid_t p2);
+/* Compare two ptids to see if they are equal.  */
+int ptid_equal (ptid_t ptid1, ptid_t ptid2);
 
-/* Return true if PTID represents a process id.  */
+/* Returns true if PTID represents a whole process, including all its
+   lwps/threads.  Such ptids have the form of (pid,0,0), with pid !=
+   -1.  */
 int ptid_is_pid (ptid_t ptid);
 
 /* Return true if PTID's lwp member is non-zero.  */