Commits

Greg Ward committed 10d1a8e

Document most of the functions in common.c.

Comments (0)

Files changed (2)

     return !!result->branch;
 }
 
-vccontext_t* init_context(const char *name,
-                          options_t* options,
-                          int (*probe)(vccontext_t*),
-                          result_t* (*get_info)(vccontext_t*))
+vccontext_t*
+init_context(const char *name,
+             options_t* options,
+             int (*probe)(vccontext_t*),
+             result_t* (*get_info)(vccontext_t*))
 {
     vccontext_t* context = (vccontext_t*) calloc(1, sizeof(vccontext_t));
     context->options = options;
     return context;
 }
 
-void free_context(vccontext_t* context)
+void
+free_context(vccontext_t* context)
 {
     free(context);
 }
 
-void debug(char* fmt, ...)
+void
+debug(char* fmt, ...)
 {
     va_list args;
 
     va_end(args);
 }
 
-static int _testmode(char* name, mode_t bits, char what[])
+static int
+_testmode(char* name, mode_t bits, char what[])
 {
     struct stat statbuf;
     if (stat(name, &statbuf) < 0) {
     return 1;
 }
 
-int isdir(char* name)
+int
+isdir(char* name)
 {
     return _testmode(name, S_IFDIR, "directory");
 }
 
-int isfile(char* name)
+int
+isfile(char* name)
 {
     return _testmode(name, S_IFREG, "regular file");
 }
 
-int read_first_line(char* filename, char* buf, int size)
+int
+read_first_line(char* filename, char* buf, int size)
 {
     FILE* file;
 
     return 1;
 }
 
-int read_last_line(char* filename, char* buf, int size)
+int
+read_last_line(char* filename, char* buf, int size)
 {
     FILE* file;
 
     return 1;
 }
 
-int read_file(const char* filename, char* buf, int size)
+int
+read_file(const char* filename, char* buf, int size)
 {
     FILE* file;
     int readsize;
     return readsize;
 }
 
-void chop_newline(char* buf)
+void
+chop_newline(char* buf)
 {
     int len = strlen(buf);
     if (buf[len-1] == '\n')
         buf[len-1] = '\0';
 }
 
-void dump_hex(const char* data, char* buf, int datasize)
+void
+dump_hex(const char* data, char* buf, int datasize)
 {
     const char HEXSTR[16] = {'0', '1', '2', '3', '4', '5', '6', '7',
                              '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
 #ifndef VCPROMPT_H
 #define VCPROMPT_H
 
+/* What the user asked for (environment + command-line).
+ */
 typedef struct {
     int debug;
     char* format;                       /* e.g. "[%b%u%m]" */
     int show_modified;                  /* show ! if local changes? */
 } options_t;
 
+/* What we figured out by analyzing the working dir: info that
+ * will be printed to stdout for the shell to incorporate into
+ * the user's prompt.
+ */
 typedef struct {
     char* branch;                       /* name of current branch */
     char* revision;                     /* current revision */
     result_t* (*get_info)(vccontext_t*);
 };
 
-void set_options(options_t*);
-vccontext_t* init_context(const char *name,
-                          options_t* options,
-                          int (*probe)(vccontext_t*),
-                          result_t* (*get_info)(vccontext_t*));
-void free_context(vccontext_t* context);
+void
+set_options(options_t*);
+vccontext_t*
+init_context(const char *name,
+             options_t* options,
+             int (*probe)(vccontext_t*),
+             result_t* (*get_info)(vccontext_t*));
+void
+free_context(vccontext_t* context);
     
-result_t* init_result();
-void free_result(result_t*);
+result_t*
+init_result();
 
-void debug(char*, ...);
+void
+free_result(result_t*);
 
-int isdir(char*);
-int isfile(char*);
-int read_first_line(char*, char*, int);
-int read_last_line(char*, char*, int);
-int read_file(const char*, char*, int);
-void chop_newline(char*);
+/* printf()-style output of fmt and other args to stdout, but only if
+ * debug mode is on (e.g. from the command line -d).
+ */
+void
+debug(char* fmt, ...);
 
-void dump_hex(const char* data, char* buf, int datasize);
+/* stat() the specified file and return true if it is a directory, false
+ * if stat() failed or it is not a directory.
+ */
+int
+isdir(char* name);
+
+/* stat() the specified file and return true if it is a regular file,
+ * false if stat() failed or it is not a regular file.
+ */
+int
+isfile(char* name);
+
+/* Open the specified file, read the first line (up to size-1 chars) to
+ * buf, and close the file.  buf will not contain a newline.  Caller
+ * must allocate at least size chars for buf.  Return 1 on successful
+ * read, 0 on any errors.  Error messages will be written with debug(),
+ * i.e. only visible if running in debug mode.
+ */
+int
+read_first_line(char* filename, char* buf, int size);
+
+/* Open the specified file, reading and discarding every line except the
+ * last.  The last line is written to buf (up to size-1 chars) without
+ * the newline.  Caller must allocate at least size chars for buf.
+ * Return value and error handling: same as read_first_line().
+ */
+int
+read_last_line(char* filename, char* buf, int size);
+
+/* Open and read the specified file to buf (up to size chars).  Caller
+ * must allocate at least size chars for buf.  buf is assumed to be
+ * binary data, i.e. not NUL-terminated.  Return value and error
+ * handling: same as read_first_line().
+ */
+int
+read_file(const char* filename, char* buf, int size);
+
+/* If the last char of buf is '\n', replace it with '\0', i.e. terminate
+ * the string one char earlier.
+ */
+void
+chop_newline(char* buf);
+
+/* Encode datasize bytes of binary data to hex chars in buf.  Caller
+ * must allocate at least datasize*2 + 1 chars for buf.
+ */
+void
+dump_hex(const char* data, char* buf, int datasize);
 
 /* Copy up to n chars from src to dest, stopping at the first newline
  * and terminating dest with a NUL char.  It is guaranteed that dest