- comments within formal arguments: last comment may be outside the
closing parenthesis. If comments are of form TYPE:COMMENT then
equivalent to @tparam not @param. See tests/factory/mymod.lua
- @constructor tag attaches CLASS. as prefix to name
- No more implicit use of "require 'pl'".
steve donovan
11 years ago
| 1 | 1 | -- Defining the ldoc document model. |
| 2 | 2 | |
| 3 | 3 | |
| 4 | require 'pl' | |
| 4 | local class = require 'pl.class' | |
| 5 | local utils = require 'pl.utils' | |
| 6 | local List = require 'pl.List' | |
| 5 | 7 | |
| 6 | 8 | local doc = {} |
| 7 | 9 | local global = require 'ldoc.builtin.globals' |
| 221 | 223 | -- if it was a class, then the name should be 'Class:foo' |
| 222 | 224 | local stype = this_mod.section.type |
| 223 | 225 | if doc.class_tag(stype) then |
| 224 | local prefix = this_mod.section.name .. ':' | |
| 225 | local i1,i2 = item.name:find(prefix) | |
| 226 | if not has_prefix(item.name,prefix) and not item.tags.constructor then | |
| 226 | local prefix = this_mod.section.name .. (not item.tags.constructor and ':' or '.') | |
| 227 | if not has_prefix(item.name,prefix) then | |
| 227 | 228 | item.name = prefix .. item.name |
| 228 | 229 | end |
| 229 | 230 | if stype == 'factory' then |
| 415 | 416 | else |
| 416 | 417 | self.parameter = 'field' |
| 417 | 418 | end |
| 418 | local params = read_del(tags,self.parameter) | |
| 419 | local names, comments, modifiers = List(), List(), List() | |
| 419 | local field = self.parameter | |
| 420 | local params = read_del(tags,field) | |
| 421 | local names, comments = List(), List() | |
| 420 | 422 | if params then |
| 421 | 423 | for line in params:iter() do |
| 422 | 424 | local name, comment = line :match('%s*([%w_%.:]+)(.*)') |
| 446 | 448 | end |
| 447 | 449 | end |
| 448 | 450 | names:append(name) |
| 449 | -- ldoc allows comments in the formal arg list to be used | |
| 450 | comments:append (fargs.comments[name] or pcomments[i] or '') | |
| 451 | local comment = pcomments[i] | |
| 452 | if not comment then | |
| 453 | -- ldoc allows comments in the formal arg list to be used, if they aren't specified with @param | |
| 454 | -- Further, these comments may start with a type followed by a colon, and are then equivalent | |
| 455 | -- to a @tparam | |
| 456 | comment = fargs.comments[name] | |
| 457 | if comment then | |
| 458 | comment = comment:gsub('^%-+%s*','') | |
| 459 | local type,rest = comment:match '([^:]+):(.*)' | |
| 460 | if type then | |
| 461 | if not self.modifiers[field] then self.modifiers[field] = List() end | |
| 462 | self.modifiers[field]:append {type = type} | |
| 463 | comment = rest | |
| 464 | end | |
| 465 | end | |
| 466 | end | |
| 467 | comments:append (comment or '') | |
| 451 | 468 | end |
| 452 | 469 | -- A formal argument of ... may match any number of params, however. |
| 453 | 470 | if #pnames > #fargs then |
| 467 | 484 | -- adding name-value pairs to the params list (this is |
| 468 | 485 | -- also done for any associated modifiers) |
| 469 | 486 | self.params = names |
| 470 | local pmods = self.modifiers[self.parameter] | |
| 487 | local pmods = self.modifiers[field] | |
| 471 | 488 | for i,name in ipairs(self.params) do |
| 472 | 489 | self.params[name] = comments[i] |
| 473 | 490 | if pmods then |
| 542 | 559 | local err = io.stderr |
| 543 | 560 | |
| 544 | 561 | local function custom_see_references (s) |
| 545 | --err:write('next',next(see_reference_handlers),'\n') | |
| 546 | 562 | for pat, action in pairs(see_reference_handlers) do |
| 547 | --err:write('pair ',pair,'\n') | |
| 548 | 563 | if s:match(pat) then |
| 549 | 564 | local label, href = action(s:match(pat)) |
| 550 | 565 | return {href = href, label = label} |
| 12 | 12 | -- generalizes the idea of these project-level categories and in fact custom categories |
| 13 | 13 | -- can be created (refered to as 'kinds' in the code) |
| 14 | 14 | |
| 15 | local List = require 'pl.List' | |
| 16 | local utils = require 'pl.utils' | |
| 17 | local path = require 'pl.path' | |
| 18 | local stringx = require 'pl.stringx' | |
| 15 | 19 | local template = require 'pl.template' |
| 16 | 20 | local tools = require 'ldoc.tools' |
| 17 | 21 | local markup = require 'ldoc.markup' |
| 2 | 2 | -- This encapsulates the different strategies needed for parsing C and Lua |
| 3 | 3 | -- source code. |
| 4 | 4 | |
| 5 | require 'pl' | |
| 6 | ||
| 5 | local class = require 'pl.class' | |
| 6 | local utils = require 'pl.utils' | |
| 7 | 7 | local tools = require 'ldoc.tools' |
| 8 | 8 | local lexer = require 'ldoc.lexer' |
| 9 | 9 |
| 2 | 2 | -- Currently just does Markdown, but this is intended to |
| 3 | 3 | -- be the general module for managing other formats as well. |
| 4 | 4 | |
| 5 | require 'pl' | |
| 6 | 5 | local doc = require 'ldoc.doc' |
| 7 | 6 | local utils = require 'pl.utils' |
| 7 | local stringx = require 'pl.stringx' | |
| 8 | 8 | local prettify = require 'ldoc.prettify' |
| 9 | 9 | local quit, concat, lstrip = utils.quit, table.concat, stringx.lstrip |
| 10 | 10 | local markup = {} |
| 0 | 0 | -- parsing code for doc comments |
| 1 | 1 | |
| 2 | require 'pl' | |
| 2 | local List = require 'pl.List' | |
| 3 | local Map = require 'pl.Map' | |
| 4 | local stringio = require 'pl.stringio' | |
| 3 | 5 | local lexer = require 'ldoc.lexer' |
| 4 | 6 | local tools = require 'ldoc.tools' |
| 5 | 7 | local doc = require 'ldoc.doc' |
| 2 | 2 | -- for known modules and functions. |
| 3 | 3 | -- A module reference to an example `test-fun.lua` would look like |
| 4 | 4 | -- `@{example:test-fun}`. |
| 5 | require 'pl' | |
| 5 | local List = require 'pl.List' | |
| 6 | 6 | local lexer = require 'ldoc.lexer' |
| 7 | 7 | local globals = require 'ldoc.builtin.globals' |
| 8 | 8 | local tnext = lexer.skipws |
| 1 | 1 | -- General utility functions for ldoc |
| 2 | 2 | -- @module tools |
| 3 | 3 | |
| 4 | require 'pl' | |
| 4 | local class = require 'pl.class' | |
| 5 | local List = require 'pl.List' | |
| 6 | local path = require 'pl.path' | |
| 7 | local utils = require 'pl.utils' | |
| 5 | 8 | local tools = {} |
| 6 | 9 | local M = tools |
| 7 | 10 | local append = table.insert |
| 299 | 302 | end |
| 300 | 303 | end |
| 301 | 304 | |
| 305 | if next(args.comments) then -- we had argument comments | |
| 306 | -- but the last one may be outside the parens! (Geoff style) | |
| 307 | local n = #args | |
| 308 | if not args.comments[n] then | |
| 309 | local t = {tok()} | |
| 310 | if type_of(t) == 'comment' then | |
| 311 | set_comment(n,t) | |
| 312 | end | |
| 313 | end | |
| 314 | end | |
| 315 | ||
| 302 | 316 | return args |
| 303 | 317 | end |
| 304 | 318 | |
| 15 | 15 | -- @license MIT/X11 |
| 16 | 16 | -- @script ldoc |
| 17 | 17 | |
| 18 | require 'pl' | |
| 18 | local class = require 'pl.class' | |
| 19 | local app = require 'pl.app' | |
| 20 | local path = require 'pl.path' | |
| 21 | local utils = require 'pl.utils' | |
| 22 | local List = require 'pl.List' | |
| 23 | local stringx = require 'pl.stringx' | |
| 24 | local tablex = require 'pl.tablex' | |
| 25 | ||
| 19 | 26 | |
| 20 | 27 | local append = table.insert |
| 21 | 28 |