search

abathur / ldmud-doc

A temporary repo for working on a revamp of the documentation system for http://github.com/ldmud/ldmud
0 stars 0 forks source link

should the content of call_other be split? #9

Closed abathur closed 7 years ago

abathur commented 8 years ago

For reasons similar to #8, I wondered if the call_other doc (https://github.com/ldmud/ldmud/blob/master/doc/efun/call_other) should be split into two documents, leaving the existing file to document the efun form, and creating a doc in LPC for the syntax-sugar form.

abathur commented 8 years ago

For the sake of transparency, the underlying functional issue here is that directives for documenting proper functions have special code which reads the function synopsis and creates cross-reference targets, index entries, etc. for the names it detects. Using these directives to document things that don't have regular function forms (or include irregular function forms in their synopsis) leads to problems (outright exceptions, errant index entries, etc.).

By contrast, the directive for documenting language features is less discriminating.

abathur commented 8 years ago

Since my personal inclination is to split these and there was no feedback, I have done so, but I'll leave this open for now. See the efun/call_other and LPC/arrow docs (source, plain and HTML) to see how I've handled the first swing at this.