Skip to content

Commit 727f248

Browse files
matzmatz
committed
Merge pull request mruby#2999 from sagmor/better-docs
More Docs
2 parents e5fbf9d + d423849 commit 727f248

20 files changed

Lines changed: 275 additions & 211 deletions

File tree

‎.yardopts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
1+
--markup markdown
12
--plugin mruby
23
--plugin coderay
34
--output-dir doc/api
5+
6+
src/**/*.c
7+
mrblib/**/*.rb
8+
include/**/*.h
9+
10+
mrbgems/*/src/**/*.c
11+
mrbgems/*/mrblib/**/*.rb
12+
mrbgems/*/include/**/*.h
413
-
514
AUTHORS
615
MITL

‎include/mruby.h‎

Lines changed: 47 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -574,42 +574,45 @@ MRB_API struct RClass * mrb_define_module_under(mrb_state *mrb, struct RClass *o
574574
#define MRB_ARGS_NONE() ((mrb_aspec)0)
575575

576576
/**
577-
* Format specifiers for \ref mrb_get_args function
578-
*
579-
* Must be a list of following format specifiers:
580-
*
581-
* | char | mruby type | retrieve types |note |
582-
* |:----:|----------------|---------------------|----------------------------------------------------|
583-
* | o | Object | mrb_value | Could be used to retrieve any type of argument |
584-
* | C | Class/Module | mrb_value | |
585-
* | S | String | mrb_value | when ! follows, the value may be nil |
586-
* | A | Array | mrb_value | when ! follows, the value may be nil |
587-
* | H | Hash | mrb_value | when ! follows, the value may be nil |
588-
* | s | String | char *, mrb_int | Receive two arguments; s! gives (NULL,0) for nil |
589-
* | z | String | char * | NUL terminated string; z! gives NULL for nil |
590-
* | a | Array | mrb_value *, mrb_int | Receive two arguments; a! gives (NULL,0) for nil |
591-
* | f | Float | mrb_float | |
592-
* | i | Integer | mrb_int | |
593-
* | b | boolean | mrb_bool | |
594-
* | n | Symbol | mrb_sym | |
595-
* | & | block | mrb_value | |
596-
* | * | rest arguments | mrb_value *, mrb_int | Receive the rest of arguments as an array. |
597-
* | \| | optional | | After this spec following specs would be optional. |
598-
* | ? | optional given | mrb_bool | True if preceding argument is given. Used to check optional argument is given. |
577+
* Format specifiers for {mrb_get_args} function
578+
*
579+
* Must be a C string composed of the following format specifiers:
580+
*
581+
* | char | Ruby type | C types | Notes |
582+
* |:----:|----------------|-------------------|----------------------------------------------------|
583+
* | `o` | {Object} | {mrb_value} | Could be used to retrieve any type of argument |
584+
* | `C` | {Class}/{Module} | {mrb_value} | |
585+
* | `S` | {String} | {mrb_value} | when `!` follows, the value may be `nil` |
586+
* | `A` | {Array} | {mrb_value} | when `!` follows, the value may be `nil` |
587+
* | `H` | {Hash} | {mrb_value} | when `!` follows, the value may be `nil` |
588+
* | `s` | {String} | char *, {mrb_int} | Receive two arguments; `s!` gives (`NULL`,`0`) for `nil` |
589+
* | `z` | {String} | char * | `NULL` terminated string; `z!` gives `NULL` for `nil` |
590+
* | `a` | {Array} | {mrb_value} *, {mrb_int} | Receive two arguments; `a!` gives (`NULL`,`0`) for `nil` |
591+
* | `f` | {Float} | {mrb_float} | |
592+
* | `i` | {Integer} | {mrb_int} | |
593+
* | `b` | boolean | {mrb_bool} | |
594+
* | `n` | {Symbol} | {mrb_sym} | |
595+
* | `&` | block | {mrb_value} | |
596+
* | `*` | rest arguments | {mrb_value} *, {mrb_int} | Receive the rest of arguments as an array. |
597+
* | | | optional | | After this spec following specs would be optional. |
598+
* | `?` | optional given | {mrb_bool} | `TRUE` if preceding argument is given. Used to check optional argument is given. |
599+
*
600+
* @see mrb_get_args
599601
*/
600602
typedef const char *mrb_args_format;
601603

602604
/**
603605
* Retrieve arguments from mrb_state.
604606
*
605-
* When applicable, implicit conversions (such as to_str, to_ary, to_hash) are
607+
* When applicable, implicit conversions (such as `to_str`, `to_ary`, `to_hash`) are
606608
* applied to received arguments.
607-
* Use it inside a function pointed by mrb_func_t.
609+
* Used inside a function of mrb_func_t type.
608610
*
609611
* @param mrb The current MRuby state.
610-
* @param format is a list of format specifiers see @ref mrb_args_format
612+
* @param format [mrb_args_format] is a list of format specifiers
611613
* @param ... The passing variadic arguments must be a pointer of retrieving type.
612614
* @return the number of arguments retrieved.
615+
* @see mrb_args_format
613616
*/
614617
MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
615618

@@ -726,7 +729,7 @@ MRB_API void mrb_close(mrb_state *mrb);
726729
/**
727730
* The default allocation function.
728731
*
729-
* @ref mrb_allocf
732+
* @see mrb_allocf
730733
*/
731734
MRB_API void* mrb_default_allocf(mrb_state*, void*, size_t, void*);
732735

@@ -854,9 +857,26 @@ MRB_API mrb_value mrb_attr_get(mrb_state *mrb, mrb_value obj, mrb_sym id);
854857
MRB_API mrb_bool mrb_respond_to(mrb_state *mrb, mrb_value obj, mrb_sym mid);
855858
MRB_API mrb_bool mrb_obj_is_instance_of(mrb_state *mrb, mrb_value obj, struct RClass* c);
856859

857-
/* fiber functions (you need to link mruby-fiber mrbgem to use) */
860+
861+
/*
862+
* Resume a Fiber
863+
*
864+
* @mrbgem mruby-fiber
865+
*/
858866
MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc, const mrb_value *argv);
867+
868+
/*
869+
* Yield a Fiber
870+
*
871+
* @mrbgem mruby-fiber
872+
*/
859873
MRB_API mrb_value mrb_fiber_yield(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
874+
875+
/*
876+
* FiberError reference
877+
*
878+
* @mrbgem mruby-fiber
879+
*/
860880
#define E_FIBER_ERROR (mrb_class_get(mrb, "FiberError"))
861881

862882
/* memory pool implementation */

‎include/mruby/error.h‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,34 @@ MRB_API mrb_noreturn void mrb_no_method_error(mrb_state *mrb, mrb_sym id, mrb_va
3232
/* declaration for fail method */
3333
MRB_API mrb_value mrb_f_raise(mrb_state*, mrb_value);
3434

35-
/* functions defined in mruby-error mrbgem */
35+
/**
36+
* Protect
37+
*
38+
* @mrbgem mruby-error
39+
*/
3640
MRB_API mrb_value mrb_protect(mrb_state *mrb, mrb_func_t body, mrb_value data, mrb_bool *state);
41+
42+
/**
43+
* Ensure
44+
*
45+
* @mrbgem mruby-error
46+
*/
3747
MRB_API mrb_value mrb_ensure(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
3848
mrb_func_t ensure, mrb_value e_data);
49+
50+
/**
51+
* Rescue
52+
*
53+
* @mrbgem mruby-error
54+
*/
3955
MRB_API mrb_value mrb_rescue(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
4056
mrb_func_t rescue, mrb_value r_data);
57+
58+
/**
59+
* Rescue exception
60+
*
61+
* @mrbgem mruby-error
62+
*/
4163
MRB_API mrb_value mrb_rescue_exceptions(mrb_state *mrb, mrb_func_t body, mrb_value b_data,
4264
mrb_func_t rescue, mrb_value r_data,
4365
mrb_int len, struct RClass **classes);

‎include/mruby/value.h‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,22 @@ enum mrb_vtype {
9898

9999
#include "mruby/object.h"
100100

101+
#ifdef MRB_DOCUMENTATION_BLOCK
102+
103+
/**
104+
* @abstract
105+
* MRuby value boxing.
106+
*
107+
* Actual implementation depends on configured boxing type.
108+
*
109+
* @see mruby/boxing_no.h Default boxing representation
110+
* @see mruby/boxing_word.h Word representation
111+
* @see mruby/boxing_nan.h Boxed double representation
112+
*/
113+
typedef void mrb_value;
114+
115+
#endif
116+
101117
#if defined(MRB_NAN_BOXING)
102118
#include "boxing_nan.h"
103119
#elif defined(MRB_WORD_BOXING)

‎mrbgems/mruby-array-ext/src/array.c‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,8 +113,9 @@ mrb_ary_values_at(mrb_state *mrb, mrb_value self)
113113
* Returns the result of interpreting <i>aray</i> as an array of
114114
* <tt>[key, value]</tt> paris.
115115
*
116-
* [[:foo, :bar], [1, 2]].to_h
117-
* # => {:foo => :bar, 1 => 2}
116+
* [[:foo, :bar], [1, 2]].to_h
117+
* # => {:foo => :bar, 1 => 2}
118+
*
118119
*/
119120

120121
static mrb_value

‎mrbgems/mruby-enum-ext/mrblib/enum.rb‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -77,11 +77,11 @@ def take(n)
7777
# Passes elements to the block until the block returns +nil+ or +false+,
7878
# then stops iterating and returns an array of all prior elements.
7979
#
80-
# If no block is given, an enumerator is returned instead.
80+
# If no block is given, an enumerator is returned instead.
81+
#
82+
# a = [1, 2, 3, 4, 5, 0]
83+
# a.take_while {|i| i < 3 } #=> [1, 2]
8184
#
82-
# a = [1, 2, 3, 4, 5, 0]
83-
# a.take_while {|i| i < 3 } #=> [1, 2]
84-
8585
def take_while(&block)
8686
return to_enum :take_while unless block
8787

@@ -94,13 +94,12 @@ def take_while(&block)
9494
end
9595

9696
##
97-
# call-seq:
98-
# enum.each_cons(n) {...} -> nil
99-
#
10097
# Iterates the given block for each array of consecutive <n>
10198
# elements.
10299
#
103-
# e.g.:
100+
# @return [nil]
101+
#
102+
# @example
104103
# (1..10).each_cons(3) {|a| p a}
105104
# # outputs below
106105
# [1, 2, 3]
@@ -127,12 +126,11 @@ def each_cons(n, &block)
127126
end
128127

129128
##
130-
# call-seq:
131-
# enum.each_slice(n) {...} -> nil
132-
#
133129
# Iterates the given block for each slice of <n> elements.
134130
#
135-
# e.g.:
131+
# @return [nil]
132+
#
133+
# @example
136134
# (1..10).each_slice(3) {|a| p a}
137135
# # outputs below
138136
# [1, 2, 3]
@@ -166,8 +164,8 @@ def each_slice(n, &block)
166164
# block, and values are arrays of elements in <i>enum</i>
167165
# corresponding to the key.
168166
#
169-
# (1..6).group_by {|i| i%3} #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
170-
167+
# (1..6).group_by {|i| i%3} #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
168+
#
171169
def group_by(&block)
172170
return to_enum :group_by unless block
173171

‎mrbgems/mruby-enum-lazy/mrblib/lazy.rb‎

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,29 @@
1-
# = Enumerable#lazy implementation
2-
#
3-
# Enumerable#lazy returns an instance of Enumerable::Lazy.
4-
# You can use it just like as normal Enumerable object,
5-
# except these methods act as 'lazy':
6-
#
7-
# - map collect
8-
# - select find_all
9-
# - reject
10-
# - grep
11-
# - drop
12-
# - drop_while
13-
# - take_while
14-
# - flat_map collect_concat
15-
# - zip
16-
#
17-
# == Acknowledgements
18-
#
19-
# Based on https://github.com/yhara/enumerable-lazy
20-
# Inspired by https://github.com/antimon2/enumerable_lz
21-
# http://jp.rubyist.net/magazine/?0034-Enumerable_lz (ja)
22-
231
module Enumerable
2+
3+
# = Enumerable#lazy implementation
4+
#
5+
# Enumerable#lazy returns an instance of Enumerable::Lazy.
6+
# You can use it just like as normal Enumerable object,
7+
# except these methods act as 'lazy':
8+
#
9+
# - map collect
10+
# - select find_all
11+
# - reject
12+
# - grep
13+
# - drop
14+
# - drop_while
15+
# - take_while
16+
# - flat_map collect_concat
17+
# - zip
2418
def lazy
2519
Lazy.new(self)
2620
end
2721

22+
# == Acknowledgements
23+
#
24+
# Based on https://github.com/yhara/enumerable-lazy
25+
# Inspired by https://github.com/antimon2/enumerable_lz
26+
# http://jp.rubyist.net/magazine/?0034-Enumerable_lz (ja)
2827
class Lazy < Enumerator
2928
def initialize(obj, &block)
3029
super(){|yielder|

0 commit comments

Comments
 (0)