search

JuliaLang / julia

The Julia Programming Language
https://julialang.org/
MIT License
45.62k stars 5.48k forks source link

List of undocumented exports for 0.2 #2242

Closed kmsquire closed 11 years ago

kmsquire commented 11 years ago

Updated 1 Aug 2013, 9:47am PST

This updated list was produced using a modified version of the julia code provided by @jiahao, now located in JULIA_HOME/doc/DocCheck.jl. A new version can be generated using

cd("$JULIA_HOME/../../doc")
import DocCheck
DocCheck.undocumented_rst()

Note that as of the merging of #3912, JULIA_HOME/doc/UNDOCUMENTED.rst contains a template for all undocumented variables. The list can also be found at http://docs.julialang.org/en/latest/UNDOCUMENTED/.

809/1183 exports have been documented (Additionally, 1 deprecated functions are still documentated)

The following exports are not documented:

Modules

Documented and deprecated functions/exports (please update docs)

pao commented 11 years ago

I know I mention this fairly frequently, but please keep in mind that @macros will ping a bunch of people not involved with Julia if we don't quote properly, so try to avoid doing that in issues! I'd like not to annoy the heck out of a bunch of people.

(Also, yes, documentation is great.)

StefanKarpinski commented 11 years ago

Yikes. That's a terrifying amount of stuff to document.

timholy commented 11 years ago

Maybe we can all do small chunks (I just did one), or put out a plea for help on the user list?

timholy commented 11 years ago

And a tip: for filling in the checkboxes, it's a good idea to do it in "Edit" mode, as the browser takes a while to update for each check.

JeffBezanson commented 11 years ago

I agree; we should divide this up among a set of volunteers. Then it could be finished quickly.

ViralBShah commented 11 years ago

Is there a way to have multiple functions share the same help? This would greatly help.

I have improved help for the linear algebra stuff on vs/linalg2 which I will pull into master, irrespective of the changes to Factorization objects.

mbaz commented 11 years ago

I can probably help with a few. Before I start, one question: where to write the docs? For example, I recently had use for isprime() and I can write its documentation. Should it go under math functions, numbers, or integers?

[pao: checked these off, and xref #2249]

timholy commented 11 years ago

Batch 2 done.

binarybana commented 11 years ago

Edit: Okay, I've got the pull request here for the collections group with some other bonuses. I only missed two: map! and endof, as I thought I'd leave those to someone with bitarray and unicode knowledge.

Unfortunately, this list of undocumented functions is only a lower bound as there are many functions where one set of arguments is documented, but not others. See help(|) and methods(|) for a bad example (though I've included docs for the |(Any,Function) format as I found its usage in the original post intriguing). But we must soldier on nonetheless! :)

timholy commented 11 years ago

Thanks, Jason. I've updated the checkboxes.

kmsquire commented 11 years ago

Someone might want to look at #2147 and rebase/merge, even though it's labeled WIP.

(Sorry not to contribute more docs myself, I have a Friday deadline to meet.)

jiahao commented 11 years ago

Just updated the list.

Here is a 15-line Julia script that will do the same if run in the Julia base directory:

havehelp = String[]
for line in split(open(readall, "usr/share/julia/helpdb.jl"), "\n")
   t = split(line, ",")
   if length(t) >= 4 && t[1][1]=='(' && contains(t[3], '"')
       push!(havehelp, replace(t[3],"\"", ""))
   end
end
exports=[strip(x) for x in split(replace(open(readall, "base/exports.jl"),",",""),"\n")]
for line in exports
    if contains(havehelp, line) || search(line, "deprecated")!=0:-1 continue end
    if length(line)>1 && line[1]=='#' && line[2]!= ' ' continue end
    if length(line)>1 && line[1]=='@' line = line[2:end] end
    if length(line)>1 && line[1]!='#' line = string("- [ ] ", line) end
    println(line)
end
kmsquire commented 11 years ago

Excellent!

andrioni commented 11 years ago

This list counts a bit wrongly some functions, as FFTW.r2r, FFTW.r2r!, FFTW.plan_r2r and FFTW.plan_r2r! all count just as FFTW.

Another thing, what's supposed to be a module documentation? We have Test and Sort documented, and some others are just imported into Base (Pkg, GMP, LinAlg).

ViralBShah commented 11 years ago

@kmsquire Could you perhaps rerun your script and update the list of functions that still need to be documented?

Everything that is exported should be documented, whether it is Base, or in a submodule.

ViralBShah commented 11 years ago

@kmsquire Would it be possible to update this list in preparation for the 0.2 release? I updated the title to reflect that this is to track documentation of functions for the 0.2 release.

kmsquire commented 11 years ago

Done. I also updated the text to indicate how anyone with write access can update this issue in the future.

kmsquire commented 11 years ago

I generated a basic template for all undocumented functions in #3912. Not quite in-place documenting, but it should make it easier for someone to fill in and copy to the right place.

vtjnash commented 11 years ago

I'm not sure where to ask this, but since I noticed it while documenting: Can I deprecate the export of the solve function? It appears to be an implementation detail of the \ operator for several special-case types and not a general purpose interface.

vtjnash commented 11 years ago

Similarly symmetrize! seems be be an odd function to export, but not it's pair symmetrize_conj!. Should both be removed or both be exported?

vtjnash commented 11 years ago

moving discussion of deprecating exports to #3950

JeffBezanson commented 11 years ago

We are getting close here. Only the following functions are left: besselh, gradient, solve, symmetrize!, xdump, mmap_grow, mmap_stream_settings, get!, fld1

I can only hope that people who know what these functions do will either document them or un-export them.

johnmyleswhite commented 11 years ago

I can document fld1, but I suspect @StefanKarpinski might prefer that we not export it at all.

andrioni commented 11 years ago

besselh is basically a way to choose between hankelh1 and hankelh2 (the pair of Bessel functions of third kind/Hankel functions):

timholy commented 11 years ago

I don't think we need to export those two mmap functions. If no one explains in the next day or so, I'll un-export them.