janet-lang / janet

A dynamic language and bytecode vm
https://janet-lang.org
MIT License
3.38k stars 217 forks source link

Cosmetically tweak module/expand-path docstring #1364

Closed sogaiu closed 5 months ago

sogaiu commented 5 months ago

This PR is an attempt to improve how the docstring of module/expand-path looks.

Currently, the text for the item having to do with :@all: doesn't look that great IMO:

    (module/expand-path path template)

    Expands a path template as found in module/paths for module/find. 
    This takes in a path (the argument to require) and a template 
    string, to expand the path to a path that can be used for importing 
    files. The replacements are as follows:

    * :all: -- the value of path verbatim.

    * :@all: -- Same as :all:, but if path starts with the @ character,
          the first path segment is replaced with a dynamic binding
          `(dyn <first path segment as keyword>)`.
              * :cur: -- the current file, or (dyn :current-file)

The proposed change should result in something that looks like:

    (module/expand-path path template)

    Expands a path template as found in module/paths for module/find. 
    This takes in a path (the argument to require) and a template 
    string, to expand the path to a path that can be used for importing 
    files. The replacements are as follows:

    * :all: -- the value of path verbatim.

    * :@all: -- Same as :all:, but if path starts with the @ character, 
      the first path segment is replaced with a dynamic binding (dyn 
      <first path segment as keyword>).

Perhaps it could be improved further [1], but this was what I was able to manage (^^;


[1] I don't know what happened to the backticks that surrounded (dyn ...) in the output, but that seems to be a different problem. I say this because the instance of "path" from:

              "* :@all: -- Same as :all:, but if `path` starts with the @ character, "

also loses its backticks in the output for the current code base as well as what's in this PR.

sogaiu commented 5 months ago

I don't know what happened to the backticks

I think this might have only been an issue on GitHub pages like this one. In a terminal session I can see the backticks with no issue.