Programmatic access?

[Alloyed]

So I'm developing an LSP server for lua. I'd like to include inline documentation, function signatures etc. Since my server and ldoc are both written in lua, It'd be nice to do this by including ldoc as a library.

the big roadblock to this afaict is ldoc.lua itself, which includes a lot of functionality, and mixes it in with the control path the main app takes. Would it be possible to split this up a bit so I can take the parts I want (project config, parsing) and leave the parts I don't (html generation, the cli)?

[stevedonovan]

This is definitely a useful and interesting problem. The task is first to work out what the interaction between the server and ldoc should be.

[Alloyed]

The absolute smallest API would probably look something like

--- get ldoc's opinion of the given file.
-- This will be a complex datatype that includes whatever info ldoc would collect, if it were generating docs.
-- When possible, return normalized datastructures, and not compiled output
-- We pass in the file text itself to avoid redundant I/O. if ldoc needs to read a bunch of files, let me know
function ldoc.parse_docs_from(file_name, file_text)
    -- imaginary output, I can adapt to whatever
    return {
        type = "table",
        module_name = "my_project.my_module",
        values = {
            { type = "function", symbol = "my_function", starts_at=, ends_at=, function_signature=, ...}
            { type = "table", symbol = "my_subtable", ...}
        }
    }
end

It will then be my server's responsibility to ask the right questions: which files to parse, has the file changed and need to be re-parsed, etc.

One interesting problem is ldoc comments embedded in C/C++ code. A lot of the time we won't have source access, but if ldoc could spit out a file that it can read later we can still support native documentation.

Since this is going into an IDE, sometimes the input file will be invalid or broken. I don't need ldoc to do anything special to handle this, just inform me somehow that it happened (eg. with error())

Just from using it I've notice the way you configure your ldoc project changes how your code is interpreted by a lot. How to handle this is an open question, but for now we can just assume the default config and fix that sort of thing later.

Thanks for considering this: I know that it's probably a lot of work, and I'm happy to contribute myself, but you probably have a much better idea of where to start and what is involved than I do.