Package list lua-ldoc / 1bf3461
doc updates Steve Donovan 8 years ago
3 changed file(s) with 40 addition(s) and 25 deletion(s). Raw diff Collapse all Expand all
224224 ## See References
225225
226226 The tag 'see' is used to reference other parts of the documentation, and 'usage' can provide
227 examples of use:
227 examples of use; there can be multiple such tags:
228228
229229 ---------
230230 -- split a string in two.
896896 thereafter references like `@{\printf}` will resolve correctly.
897897
898898 If you look at the source for this document, you will see a `@lookup doc.md` which allows
899 direct references to sections like @{Readme_files|this}.
899 direct references to sections like @{Readme_files|this} with `@{\Readme_files|this}`.
900900
901901 Remember that the default is for references in backticks to be resolved; unlike @
902902 references, it is not an error if the reference cannot be found.
905905 particular section can be refered to as `@{\doc.md.Resolving_References_in_Documents}` - the
906906 rule is that any non-alphabetic character is replaced by an underscore.
907907
908
909908 ## Tag Modifiers
910909
911910 Ay tag may have _tag modifiers_. For instance, you may say
912911 `@param[type=number]` and this associates the modifier `type` with value `number` with this
913 particular param tag. A shorthand can be introduced for this common case, which is `@tparam
912 particular param tag. A shorthand has been introduced for this common case, which is `@tparam
914913 <type> <parmname> <comment>`; in the same way `@treturn` is defined.
915914
916915 This is useful for larger projects where you want to provide the argument and return value
917 types for your API, in a structured way that can be easily extracted later. There is a
918 useful function for creating new tags that can be used in `config.ld`:
916 types for your API, in a structured way that can be easily extracted later.
917
918 These types can be combined, so that "?string|number" means "ether a string or a number";
919 "?string" is short for "?|nil|string". However, for this last case you should usually use the
920 `opt` modifier discussed below.
921
922 There is a useful function for creating new tags that can be used in `config.ld`:
919923
920924 tparam_alias('string','string')
921925
922 That is, "@string" will now have the same meaning as "@tparam string".
926 That is, "@string" will now have the same meaning as "@tparam string"; this also applies
927 to the optional type syntax "?|T1|T2".
923928
924929 From 1.3, the following standard type aliases are predefined:
925930
931936 * `tab` 'table'
932937 * `thread`
933938
934 The exact form of `<type>` is not defined, but here is a suggested scheme:
935
936 number -- a plain type
937 Bonzo -- a known type; a reference link will be generated
938 {string,number} -- a 'list' tuple, built from type expressions
939 {A=string,N=number} -- a 'struct' tuple, ditto
940 {Bonzo,...} -- an array of Bonzo objects
941 {[string]=Bonzo,...} -- a map of Bonzo objects with string keys
942 Array(Bonzo) -- (assuming that Array is a container)
943
944 Currently the `type` modifier is the only one known and used by LDoc when generating HTML
945 output. However, any other modifiers are allowed and are available for use with your own
946 templates or for extraction by your own tools.
939 When using 'colon-style' (@{colon.lua}) it's possible to directly use types by prepending
940 them with '!'; '?' is also naturally understood.
941
942 The exact form of `<type>` is not defined, but here is one suggested scheme:
943
944 * `number` -- a plain type
945 * `Bonzo` -- a known type; a reference link will be generated
946 * `{string,number}` -- a 'list' tuple of two values, built from type expressions
947 * `{A=string,N=number}` -- a 'struct', ditto (But it's often better to create a named table and refer to it)
948 * `{Bonzo,...}` -- an array of Bonzo objects
949 * `{[string]=Bonzo,...}` -- a map of Bonzo objects with string keys
950 * `Array(Bonzo)` -- (assuming that Array is a container type)
947951
948952 The `alias` function within configuration files has been extended so that alias tags can be
949953 defined as a tag plus a set of modifiers. So `tparam` is defined as:
965969 end
966970 ----> displayed as: two (one [, two], three [, four])
967971
968 This modifier can also be used with type aliases. If a value is given for the modifier
972 This modifier can also be used with type aliases. If a value is given for `opt`
969973 then LDoc can present this as the default value for this optional argument.
970974
971975 --- a function with typed args.
979983 function one (name,age,...)
980984 end
981985 ----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
986
987 Currently the `type` and `opt` modifiers are the only ones known and used by LDoc when generating HTML
988 output. However, any other modifiers are allowed and are available for use with your own
989 templates or for extraction by your own tools.
982990
983991 (See @{four.lua})
984992
10051013 - `merge` allow documentation from different files to be merged into modules without
10061014 explicit @submodule tag
10071015
1008 _These only appear in `config.ld`:_
1016 _These only appear in config.ld:_
10091017
10101018 - `description` a short project description used under the project title
10111019 - `full_description` when you _really_ need a longer project description
1010
1111 --- first useless function.
1212 -- Optional type specifiers are allowed in this format.
13 -- As an extension, '?' is short for '?|'.
13 -- As an extension, '?T' is short for '?nil|T'.
1414 -- Note how these types are rendered!
1515 -- string: name
1616 -- int: age
17 -- ?person2: options
17 -- ?person3: options
1818 -- treturn: ?table|string
1919 function one (name,age,options)
2020 end
21
22 --- implicit table can always use colon notation.
23 person2 = {
24 id=true, -- string: official ID number
25 sex=true, -- string: one of 'M', 'F' or 'N'
26 spouse=true, -- ?person3: wife or husband
27 }
2128
2229 --- explicit table in colon format.
2330 -- Note how '!' lets you use a type name directly.
1010 -- Note the the standard tparam aliases, and how the 'opt' and 'optchain'
1111 -- modifiers may also be used. If the Lua function has varargs, then
1212 -- you may document an indefinite number of extra arguments!
13 -- @string name person's name
13 -- @tparam ?string|Person name person's name
1414 -- @int age
1515 -- @string[opt='gregorian'] calender optional calendar
1616 -- @int[opt=0] offset optional offset