Commit 880957ad authored by ZyX's avatar ZyX Committed by Thiago de Arruda

Move documentation from function declarations to definitions

Uses a perl script to move it (scripts/movedocs.pl)
parent 52a9a5b0
#!/usr/bin/perl
use strict;
use warnings;
if ($ARGV[0] eq '--help') {
print << "EOF";
Usage:
$0 file.h file.c
Removes documentation attached to function declarations in file.h and adds them
to function definitions found in file.c.
$0 file.c
Moves documentation attached to function declaration present in the same file as
the definition.
EOF
exit 0;
}
my $hfile = shift @ARGV;
my @cfiles = @ARGV;
my %docs = ();
my $F;
sub write_lines {
my $file = shift;
my @lines = @_;
my $F;
open $F, '>', $file;
print $F (join "", @lines);
close $F;
}
if (@cfiles) {
open $F, '<', $hfile
or die "Failed to open $hfile.";
my @hlines = ();
my $lastdoc = '';
while (<$F>) {
if (/^\/\/\/?/) {
$lastdoc .= $_;
} elsif (/^\S.*?(\w+)\(.*(?:,|\);?|FUNC_ATTR_\w+;?)$/) {
die "Documentation for $1 was already defined" if (defined $docs{$1});
if ($lastdoc ne '') {
$docs{$1} = $lastdoc;
$lastdoc = '';
}
push @hlines, $_;
} elsif ($lastdoc ne '') {
push @hlines, $lastdoc;
$lastdoc = '';
push @hlines, $_;
} else {
push @hlines, $_;
}
}
close $F;
my %clines_hash = ();
for my $cfile (@cfiles) {
open $F, '<', $cfile
or die "Failed to open $cfile.";
my @clines = ();
while (<$F>) {
if (/^\S.*?(\w+)\(.*[,)]$/ and defined $docs{$1}) {
push @clines, $docs{$1};
delete $docs{$1};
} elsif (/^(?!static\s)\S.*?(\w+)\(.*[,)]$/ and not defined $docs{$1}) {
print STDERR "Documentation not defined for $1\n";
}
push @clines, $_;
}
close $F;
$clines_hash{$cfile} = \@clines;
}
while (my ($func, $value) = each %docs) {
die "Function not found: $func\n";
}
write_lines($hfile, @hlines);
while (my ($cfile, $clines) = each %clines_hash) {
write_lines($cfile, @$clines);
}
} else {
open $F, '<', $hfile;
my @lines;
my $lastdoc = '';
my $defstart = '';
my $funcname;
sub clear_lastdoc {
if ($lastdoc ne '') {
push @lines, $lastdoc;
$lastdoc = '';
}
}
sub record_lastdoc {
my $funcname = shift;
if ($lastdoc ne '') {
$docs{$funcname} = $lastdoc;
$lastdoc = '';
}
}
sub add_doc {
my $funcname = shift;
if (defined $docs{$funcname}) {
push @lines, $docs{$funcname};
delete $docs{$funcname};
}
}
sub clear_defstart {
push @lines, $defstart;
$defstart = '';
}
while (<$F>) {
if (/\/\*/ .. /\*\// and not /\/\*.*?\*\//) {
push @lines, $_;
} elsif (/^\/\/\/?/) {
$lastdoc .= $_;
} elsif (/^\S.*?(\w+)\(.*(?:,|(\);?))$/) {
if (not $2) {
$defstart .= $_;
$funcname = $1;
} elsif ($2 eq ');') {
record_lastdoc $1;
push @lines, $_;
} elsif ($2 eq ')') {
clear_lastdoc;
add_doc $1;
push @lines, $_;
}
} elsif ($defstart ne '') {
$defstart .= $_;
if (/[{}]/) {
clear_lastdoc;
clear_defstart;
} elsif (/\);$/) {
record_lastdoc $funcname;
clear_defstart;
} elsif (/\)$/) {
clear_lastdoc;
add_doc $funcname;
clear_defstart;
}
} else {
clear_lastdoc;
push @lines, $_;
}
}
close $F;
while (my ($func, $value) = each %docs) {
die "Function not found: $func\n";
}
write_lines($hfile, @lines);
}
......@@ -20,10 +20,6 @@
#include "nvim/window.h"
#include "nvim/undo.h"
// Find a window that contains "buf" and switch to it.
// If there is no such window, use the current window and change "curbuf".
// Caller must initialize save_curbuf to NULL.
// restore_win_for_buf() MUST be called later!
static void switch_to_win_for_buf(buf_T *buf,
win_T **save_curwinp,
tabpage_T **save_curtabp,
......@@ -33,14 +29,15 @@ static void restore_win_for_buf(win_T *save_curwin,
tabpage_T *save_curtab,
buf_T *save_curbuf);
// Check if deleting lines made the cursor position invalid.
// Changed the lines from "lo" to "hi" and added "extra" lines (negative if
// deleted).
static void fix_cursor(linenr_T lo, linenr_T hi, linenr_T extra);
// Normalizes 0-based indexes to buffer line numbers
static int64_t normalize_index(buf_T *buf, int64_t index);
/// Gets the buffer line count
///
/// @param buffer The buffer handle
/// @param[out] err Details of an error that may have occurred
/// @return The line count
Integer buffer_get_length(Buffer buffer, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
......@@ -52,6 +49,12 @@ Integer buffer_get_length(Buffer buffer, Error *err)
return buf->b_ml.ml_line_count;
}
/// Gets a buffer line
///
/// @param buffer The buffer handle
/// @param index The line index
/// @param[out] err Details of an error that may have occurred
/// @return The line string
String buffer_get_line(Buffer buffer, Integer index, Error *err)
{
String rv = {.size = 0};
......@@ -66,18 +69,38 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
return rv;
}
/// Sets a buffer line
///
/// @param buffer The buffer handle
/// @param index The line index
/// @param line The new line.
/// @param[out] err Details of an error that may have occurred
void buffer_set_line(Buffer buffer, Integer index, String line, Error *err)
{
StringArray array = {.items = &line, .size = 1};
buffer_set_slice(buffer, index, index, true, true, array, err);
}
/// Deletes a buffer line
///
/// @param buffer The buffer handle
/// @param index The line index
/// @param[out] err Details of an error that may have occurred
void buffer_del_line(Buffer buffer, Integer index, Error *err)
{
StringArray array = ARRAY_DICT_INIT;
buffer_set_slice(buffer, index, index, true, true, array, err);
}
/// Retrieves a line range from the buffer
///
/// @param buffer The buffer handle
/// @param start The first line index
/// @param end The last line index
/// @param include_start True if the slice includes the `start` parameter
/// @param include_end True if the slice includes the `end` parameter
/// @param[out] err Details of an error that may have occurred
/// @return An array of lines
StringArray buffer_get_slice(Buffer buffer,
Integer start,
Integer end,
......@@ -128,6 +151,16 @@ end:
return rv;
}
/// Replaces a line range on the buffer
///
/// @param buffer The buffer handle
/// @param start The first line index
/// @param end The last line index
/// @param include_start True if the slice includes the `start` parameter
/// @param include_end True if the slice includes the `end` parameter
/// @param lines An array of lines to use as replacement(A 0-length array
/// will simply delete the line range)
/// @param[out] err Details of an error that may have occurred
void buffer_set_slice(Buffer buffer,
Integer start,
Integer end,
......@@ -251,6 +284,12 @@ end:
try_end(err);
}
/// Gets a buffer variable
///
/// @param buffer The buffer handle
/// @param name The variable name
/// @param[out] err Details of an error that may have occurred
/// @return The variable value
Object buffer_get_var(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
......@@ -262,6 +301,13 @@ Object buffer_get_var(Buffer buffer, String name, Error *err)
return dict_get_value(buf->b_vars, name, err);
}
/// Sets a buffer variable. Passing 'nil' as value deletes the variable.
///
/// @param buffer The buffer handle
/// @param name The variable name
/// @param value The variable value
/// @param[out] err Details of an error that may have occurred
/// @return The old value
Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
......@@ -273,6 +319,12 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
return dict_set_value(buf->b_vars, name, value, err);
}
/// Gets a buffer option value
///
/// @param buffer The buffer handle
/// @param name The option name
/// @param[out] err Details of an error that may have occurred
/// @return The option value
Object buffer_get_option(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
......@@ -284,6 +336,13 @@ Object buffer_get_option(Buffer buffer, String name, Error *err)
return get_option_from(buf, SREQ_BUF, name, err);
}
/// Sets a buffer option value. Passing 'nil' as value deletes the option(only
/// works if there's a global fallback)
///
/// @param buffer The buffer handle
/// @param name The option name
/// @param value The option value
/// @param[out] err Details of an error that may have occurred
void buffer_set_option(Buffer buffer, String name, Object value, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
......@@ -295,6 +354,11 @@ void buffer_set_option(Buffer buffer, String name, Object value, Error *err)
set_option_to(buf, SREQ_BUF, name, value, err);
}
/// Gets the buffer number
///
/// @param buffer The buffer handle
/// @param[out] err Details of an error that may have occurred
/// @return The buffer number
Integer buffer_get_number(Buffer buffer, Error *err)
{
Integer rv = 0;
......@@ -307,6 +371,11 @@ Integer buffer_get_number(Buffer buffer, Error *err)
return buf->b_fnum;
}
/// Gets the full file name for the buffer
///
/// @param buffer The buffer handle
/// @param[out] err Details of an error that may have occurred
/// @return The buffer name
String buffer_get_name(Buffer buffer, Error *err)
{
String rv = STRING_INIT;
......@@ -319,6 +388,11 @@ String buffer_get_name(Buffer buffer, Error *err)
return cstr_to_string((char *)buf->b_ffname);
}
/// Sets the full file name for a buffer
///
/// @param buffer The buffer handle
/// @param name The buffer name
/// @param[out] err Details of an error that may have occurred
void buffer_set_name(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
......@@ -347,17 +421,34 @@ void buffer_set_name(Buffer buffer, String name, Error *err)
}
}
/// Checks if a buffer is valid
///
/// @param buffer The buffer handle
/// @return true if the buffer is valid, false otherwise
Boolean buffer_is_valid(Buffer buffer)
{
Error stub = {.set = false};
return find_buffer(buffer, &stub) != NULL;
}
/// Inserts a sequence of lines to a buffer at a certain index
///
/// @param buffer The buffer handle
/// @param lnum Insert the lines after `lnum`. If negative, it will append
/// to the end of the buffer.
/// @param lines An array of lines
/// @param[out] err Details of an error that may have occurred
void buffer_insert(Buffer buffer, Integer lnum, StringArray lines, Error *err)
{
buffer_set_slice(buffer, lnum, lnum, false, true, lines, err);
}
/// Return a tuple (row,col) representing the position of the named mark
///
/// @param buffer The buffer handle
/// @param name The mark's name
/// @param[out] err Details of an error that may have occurred
/// @return The (row, col) tuple
Position buffer_get_mark(Buffer buffer, String name, Error *err)
{
Position rv = POSITION_INIT;
......@@ -395,6 +486,10 @@ Position buffer_get_mark(Buffer buffer, String name, Error *err)
return rv;
}
// Find a window that contains "buf" and switch to it.
// If there is no such window, use the current window and change "curbuf".
// Caller must initialize save_curbuf to NULL.
// restore_win_for_buf() MUST be called later!
static void switch_to_win_for_buf(buf_T *buf,
win_T **save_curwinp,
tabpage_T **save_curtabp,
......@@ -419,6 +514,9 @@ static void restore_win_for_buf(win_T *save_curwin,
}
}
// Check if deleting lines made the cursor position invalid.
// Changed the lines from "lo" to "hi" and added "extra" lines (negative if
// deleted).
static void fix_cursor(linenr_T lo, linenr_T hi, linenr_T extra)
{
if (curwin->w_cursor.lnum >= lo) {
......@@ -438,6 +536,7 @@ static void fix_cursor(linenr_T lo, linenr_T hi, linenr_T extra)
invalidate_botline();
}
// Normalizes 0-based indexes to buffer line numbers
static int64_t normalize_index(buf_T *buf, int64_t index)
{
// Fix if < 0
......
......@@ -6,45 +6,14 @@
#include "nvim/api/private/defs.h"
/// Gets the buffer line count
///
/// @param buffer The buffer handle
/// @param[out] err Details of an error that may have occurred
/// @return The line count
Integer buffer_get_length(Buffer buffer, Error *err);
/// Gets a buffer line
///
/// @param buffer The buffer handle
/// @param index The line index
/// @param[out] err Details of an error that may have occurred
/// @return The line string
String buffer_get_line(Buffer buffer, Integer index, Error *err);
/// Sets a buffer line
///
/// @param buffer The buffer handle
/// @param index The line index
/// @param line The new line.
/// @param[out] err Details of an error that may have occurred
void buffer_set_line(Buffer buffer, Integer index, String line, Error *err);
/// Deletes a buffer line
///
/// @param buffer The buffer handle
/// @param index The line index
/// @param[out] err Details of an error that may have occurred
void buffer_del_line(Buffer buffer, Integer index, Error *err);
/// Retrieves a line range from the buffer
///
/// @param buffer The buffer handle
/// @param start The first line index
/// @param end The last line index
/// @param include_start True if the slice includes the `start` parameter
/// @param include_end True if the slice includes the `end` parameter
/// @param[out] err Details of an error that may have occurred
/// @return An array of lines
StringArray buffer_get_slice(Buffer buffer,
Integer start,
Integer end,
......@@ -52,16 +21,6 @@ StringArray buffer_get_slice(Buffer buffer,
Boolean include_end,
Error *err);
/// Replaces a line range on the buffer
///
/// @param buffer The buffer handle
/// @param start The first line index
/// @param end The last line index
/// @param include_start True if the slice includes the `start` parameter
/// @param include_end True if the slice includes the `end` parameter
/// @param lines An array of lines to use as replacement(A 0-length array
/// will simply delete the line range)
/// @param[out] err Details of an error that may have occurred
void buffer_set_slice(Buffer buffer,
Integer start,
Integer end,
......@@ -70,82 +29,24 @@ void buffer_set_slice(Buffer buffer,
StringArray replacement,
Error *err);
/// Gets a buffer variable
///
/// @param buffer The buffer handle
/// @param name The variable name
/// @param[out] err Details of an error that may have occurred
/// @return The variable value
Object buffer_get_var(Buffer buffer, String name, Error *err);
/// Sets a buffer variable. Passing 'nil' as value deletes the variable.
///
/// @param buffer The buffer handle
/// @param name The variable name
/// @param value The variable value
/// @param[out] err Details of an error that may have occurred
/// @return The old value
Object buffer_set_var(Buffer buffer, String name, Object value, Error *err);
/// Gets a buffer option value
///
/// @param buffer The buffer handle
/// @param name The option name
/// @param[out] err Details of an error that may have occurred
/// @return The option value
Object buffer_get_option(Buffer buffer, String name, Error *err);
/// Sets a buffer option value. Passing 'nil' as value deletes the option(only
/// works if there's a global fallback)
///
/// @param buffer The buffer handle
/// @param name The option name
/// @param value The option value
/// @param[out] err Details of an error that may have occurred
void buffer_set_option(Buffer buffer, String name, Object value, Error *err);
/// Gets the buffer number
///
/// @param buffer The buffer handle
/// @param[out] err Details of an error that may have occurred
/// @return The buffer number
Integer buffer_get_number(Buffer buffer, Error *err);
/// Gets the full file name for the buffer
///
/// @param buffer The buffer handle
/// @param[out] err Details of an error that may have occurred
/// @return The buffer name
String buffer_get_name(Buffer buffer, Error *err);
/// Sets the full file name for a buffer
///
/// @param buffer The buffer handle
/// @param name The buffer name
/// @param[out] err Details of an error that may have occurred
void buffer_set_name(Buffer buffer, String name, Error *err);
/// Checks if a buffer is valid
///
/// @param buffer The buffer handle
/// @return true if the buffer is valid, false otherwise
Boolean buffer_is_valid(Buffer buffer);
/// Inserts a sequence of lines to a buffer at a certain index
///
/// @param buffer The buffer handle
/// @param lnum Insert the lines after `lnum`. If negative, it will append
/// to the end of the buffer.
/// @param lines An array of lines
/// @param[out] err Details of an error that may have occurred
void buffer_insert(Buffer buffer, Integer lnum, StringArray lines, Error *err);
/// Return a tuple (row,col) representing the position of the named mark
///
/// @param buffer The buffer handle
/// @param name The mark's name
/// @param[out] err Details of an error that may have occurred
/// @return The (row, col) tuple
Position buffer_get_mark(Buffer buffer, String name, Error *err);
#endif // NVIM_API_BUFFER_H
......
......@@ -15,12 +15,6 @@
#include "nvim/option.h"
#include "nvim/option_defs.h"
/// Recursion helper for the `vim_to_object`. This uses a pointer table
/// to avoid infinite recursion due to cyclic references
///
/// @param obj The source object
/// @param lookup Lookup table containing pointers to all processed objects
/// @return The converted value
static Object vim_to_object_rec(typval_T *obj, PMap(ptr_t) *lookup);
static bool object_to_vim(Object obj, typval_T *tv, Error *err);
......@@ -39,11 +33,17 @@ static void set_option_value_err(char *key,
int opt_flags,
Error *err);
/// Start block that may cause vimscript exceptions
void try_start()
{
++trylevel;
}
/// End try block, set the error message if any and return true if an error
/// occurred.
///
/// @param err Pointer to the stack-allocated error object
/// @return true if an error occurred
bool try_end(Error *err)
{
--trylevel;
......@@ -81,6 +81,11 @@ bool try_end(Error *err)
return err->set;
}
/// Recursively expands a vimscript value in a dict
///
/// @param dict The vimscript dict
/// @param key The key
/// @param[out] err Details of an error that may have occurred
Object dict_get_value(dict_T *dict, String key, Error *err)
{
Object rv = OBJECT_INIT;
......@@ -101,6 +106,14 @@ Object dict_get_value(dict_T *dict, String key, Error *err)
return rv;
}
/// Set a value in a dict. Objects are recursively expanded into their
/// vimscript equivalents. Passing 'nil' as value deletes the key.
///
/// @param dict The vimscript dict
/// @param key The key
/// @param value The new value
/// @param[out] err Details of an error that may have occurred
/// @return the old value, if any
Object dict_set_value(dict_T *dict, String key, Object value, Error *err)
{
Object rv = OBJECT_INIT;
......@@ -164,6 +177,14 @@ Object dict_set_value(dict_T *dict, String key, Object value, Error *err)
return rv;
}
/// Gets the value of a global or local(buffer, window) option.
///
/// @param from If `type` is `SREQ_WIN` or `SREQ_BUF`, this must be a pointer
/// to the window or buffer.
/// @param type One of `SREQ_GLOBAL`, `SREQ_WIN` or `SREQ_BUF`
/// @param name The option name
/// @param[out] err Details of an error that may have occurred
/// @return the option value
Object get_option_from(void *from, int type, String name, Error *err)
{
Object rv = OBJECT_INIT;
......@@ -207,6 +228,13 @@ Object get_option_from(void *from, int type, String name, Error *err)
return rv;
}
/// Sets the value of a global or local(buffer, window) option.
///
/// @param to If `type` is `SREQ_WIN` or `SREQ_BUF`, this must be a pointer
/// to the window or buffer.
/// @param type One of `SREQ_GLOBAL`, `SREQ_WIN` or `SREQ_BUF`
/// @param name The option name
/// @param[out] err Details of an error that may have occurred
void set_option_to(void *to, int type, String name, Object value, Error *err)
{
if (name.size == 0) {
......@@ -274,6 +302,11 @@ cleanup:
free(key);
}
/// Convert a vim object to an `Object` instance, recursively expanding
/// Arrays/Dictionaries.
///
/// @param obj The source object
/// @return The converted value
Object vim_to_object(typval_T *obj)
{
Object rv;
......@@ -285,6 +318,11 @@ Object vim_to_object(typval_T *obj)
return rv;
}
/// Finds the pointer for a window number
///
/// @param window the window number
/// @param[out] err Details of an error that may have occurred
/// @return the window pointer
buf_T *find_buffer(Buffer buffer, Error *err)
{
buf_T *rv = handle_get_buffer(buffer);
......@@ -296,6 +334,11 @@ buf_T *find_buffer(Buffer buffer, Error *err)
return rv;
}
/// Finds the pointer for a window number
///
/// @param window the window number
/// @param[out] err Details of an error that may have occurred
/// @return the window pointer
win_T * find_window(Window window, Error *err)
{
win_T *rv = handle_get_window(window);
......@@ -307,6 +350,11 @@ win_T * find_window(Window window, Error *err)
return rv;
}
/// Finds the pointer for a tabpage number
///
/// @param tabpage the tabpage number
/// @param[out] err Details of an error that may have occurred
/// @return the tabpage pointer
tabpage_T * find_tab(Tabpage tabpage, Error *err)
{
tabpage_T *rv = handle_get_tabpage(tabpage);
......@@ -422,6 +470,12 @@ static bool object_to_vim(Object obj, typval_T *tv, Error *err)
return true;
}
/// Recursion helper for the `vim_to_object`. This uses a pointer table
/// to avoid infinite recursion due to cyclic references
///
/// @param obj The source object
/// @param lookup Lookup table containing pointers to all processed objects
/// @return The converted value
static Object vim_to_object_rec(typval_T *obj, PMap(ptr_t) *lookup)
{
Object rv = OBJECT_INIT;
......
......@@ -13,78 +13,24 @@
err->set = true; \
} while (0)
/// Start block that may cause vimscript exceptions
void try_start(void);
/// End try block, set the error message if any and return true if an error
/// occurred.
///
/// @param err Pointer to the stack-allocated error object
/// @return true if an error occurred
bool try_end(Error *err);
/// Recursively expands a vimscript value in a dict
///
/// @param dict The vimscript dict
/// @param key The key
/// @param[out] err Details of an error that may have occurred
Object dict_get_value(dict_T *dict, String key, Error *err);
/// Set a value in a dict. Objects are recursively expanded into their
/// vimscript equivalents. Passing 'nil' as value deletes the key.
///
/// @param dict The vimscript dict
/// @param key The key
/// @param value The new value
/// @param[out] err Details of an error that may have occurred
/// @return the old value, if any
Object dict_set_value(dict_T *dict, String key, Object value, Error *err);
/// Gets the value of a global or local(buffer, window) option.
///
/// @param from If `type` is `SREQ_WIN` or `SREQ_BUF`, this must be a pointer
/// to the window or buffer.
</