How to document my file-loader

[mauro3]

How/where would I document the keyword arguments of some specific loader, ideally using Julia's help system? Just adding a doc-string to each load method doesn't work, as that would make for a super long concatenated doc-string. Maybe add it to the format-string somehow?

[SimonDanisch]

Interesting question, we should definitely have a nice solution for this! The format string seems to be a good place!

[mauro3]

Is there a central place where the format-strings are stored?

[SimonDanisch]

Well, it's a type:

julia> format"PBMBinary"
FileIO.DataFormat{:PBMBinary}

Still looking at the docs, if a type with parameters can be explicitly documented.

[SimonDanisch]

Maybe add it to the IO package module?

[mauro3]

I don't think one can document types with parameters separately for different parameters.

To actually be able to find the documentation of a loader, some call involving the file itself would be best as remembering anything else will be impossible. Maybe help("pic.png") or helpIO("pic.png")? These suggestions fall outside the julia-help system. But I don't think it can be used directly as a function call needs to be done to transform "pic.png" into something to which a doc-string can be attached.

Let's call @MichaelHatherly to the rescue! Do you have any idea on how to do this within the help system?

[MichaelHatherly]

The doc concatenation can be a bit annoying sometimes... though you should be able to search for docs for methods that only match a specific signature with:

julia> "docs for `load`"
       function load end
load

julia> type DataFormat{Sym} end

julia> "docs for png `load`"
       load(::DataFormat{:png}) = nothing
load

julia> macro format_str(text) DataFormat{Symbol(text)} end
@format_str (macro with 1 method)

help?> load(::format"png")
  docs for png load

help?> load
search: LoadError LOAD_PATH reload download unsafe_load logabsdet localindexes clipboard

  docs for load

  docs for png load

Doesn't look like the :: syntax for ? mode is documented currently, probably worth adding that somewhere in the manual.

[mauro3]

(+1 to documenting the :: syntax.)

But that then means that the doc-string returned by ?load is huge, as it is the concatenation of all of the method doc-strings (currently there are about 50 registered formats). I guess that might be a problem in other use cases too.

Perfect would be if:

• ?load("foo.sif") could be made to work as remembering something like format"AndorSIF" would be hard.
• ?load would just show the function doc and not the docs of all methods.

But I can't see how this could be made to work. So how about making a function docIO("foo.sif") and register a doc-string with the add_format?

[SimonDanisch]

Yeah, that'd be the sane approach!

[mauro3]

Isn't this https://github.com/JuliaLang/julia/pull/20142 what we need here?

[SimonDanisch]

Looks like it :)

On 20 Jan 2017 3:41 p.m., "Mauro" [email protected] wrote:

Isn't this JuliaLang/julia#20142 https://github.com/JuliaLang/julia/pull/20142 what we need here?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/JuliaIO/FileIO.jl/issues/97#issuecomment-274087844, or mute the thread https://github.com/notifications/unsubscribe-auth/AA9rIyxPybo6W7W_RVOh55tGbVxpWtzvks5rUMebgaJpZM4LnRcU .