make @submodule 'pull' instead of 'push'

[dmccuskey]

trafficstars

i write a lot of object oriented Lua and i would like for a @module to pull in content from multiple files (i.e., the superclasses).

as it stands, with the current implementation of @submodule a subfile can ONLY be used with a SINGLE @module. this is because the "power" is given to the subfile to determine where it's going to go, so it essentially "pushes" itself into another @module. reversing this so that a @module lists multiple @submodules to "pull" into itself, allows for HUGE reuse and more flexibility with documentation (esp for OO code) and code structure. mind you, defining the @submodule order would matter so functions that already existed in the namespace wouldn't get pulled in again (eg, for method overrides).

i looked at issue #17, and the solution for merging seems no different that what @submodule already provides. essentially some subfile is declaring the @module to which it wants assigned (push). however, the idea in that thread about @internal could be used so a subfile marked this way doesn't generate its own doc page, yet other modules could still pull content from it.

to maintain backwards compatibility, this tag could have a different name, for example @superclass :)

for example:

@module animal

@module dog @superclass animal

@module cat @superclass animal

the example in #17 could simply be this (without the need for the merge functionality)

file1.c @module blitwizard @superclass subblitwizard2, subblitwizard3

file2.c @module subblitwizard2 @internal

file3.c @module subblitwizard3 @internal

i think this follows LDoc's stated goal to "get out of the way of the developer" – LDoc is still "module" centric (which is nice), but would now have NO relationship to files. for example, you could have a file with ZERO code marked with @module and, via @submodule-"pull" functionality, it could pick and choose its content as it needs. as mentioned, marking a file as @internal will block any file from having its own documentation page, so devs could organize as they wish and files hidden as required. simply put, there only needs to be a file which "represents" the module page you want to put together and it decides its own content choosing from all of the available files in the project.

i'd be happy if you said there was a feature already available which would do this. :) until then, i think my only option is to create some bogus functions representing methods from superclasses and rename them with @function.

[stevedonovan]

I like this idea, since we are getting away module-is-a-file. Let me have a look and see if we can't do a preview for 1.4.4

[Xemiru]

Supporting this, as I also do a lot of oop; @submodule does not let me define multiple modules to be a part of.