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

Why is array/string-indexing documentation (efun/[]) located in efun instead of LPC? #8

Closed abathur closed 8 years ago

abathur commented 8 years ago

Is the doc on indexing arrays and strings (see: https://github.com/ldmud/ldmud/blob/master/doc/efun/%5B%5D) in efun for a specific ongoing reason, or just because it was historically kept there when the functionality was performed by efuns?

It seems to me like this doc should be in /LPC/, but I realize there might be something subtle I don't understand about why it is where it is.

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 there's been no discussion, I have moved this document to LPC/index.rst and 'named' the actual language feature []. Closing for now and we can revisit if an explanation for why it should be in efun surfaces.