Roadmap: Documentation about lazysets.jl HOT 18 CLOSED

Let me do it.

from lazysets.jl.

2. Do we want to have rules for line breaks in the signatures?

i think that we shall have: "try to stay within 80 characters". apart from that, i'm not sure that we want to have a general rule, usually if the arguments fit in one line then it looks nice, but if there are many arguments it looks nicer if they are in different rows. this is subjective of course and also for this reason i don't advocate to a strict rule here.

from lazysets.jl.

5. We should merge the sections on developing in about.md and getting_started.md (I forgot that we already had this). Where should we put it?

i feel like "development" doesn't fit in the "Getting Started" section. that was the reason to put it in the about.md otherwise, we can have a new section "Contributing", as in documenter.

from lazysets.jl.

the function unit_step is a misnomer -- this function returns 0 for negative values of its argument. moreover its current docstring doesn't make sense:

    unit_step(x::Real)

The unit step function, which returns 1 iff x is greater than or equal to zero.

should we name it to sign_right to say that it is continuous from the right?

from lazysets.jl.

Cool, I edited a bit. By the way, I found out how to write triple backticks in markdown code blocks: Just write the code blocks with quadruple backticks 🤕, like this:

````julia
some text
```
text in triple backticks
```
after the backticks
````

(Guess how I wrote this block 👀)

from lazysets.jl.

Can you elaborate which doc style we should follow?
The Julia guidelines?

I like that struct fields can be commented in the code.
EDIT: Documenter.jl does not seem to recognize this, so we should document fields as before.

from lazysets.jl.

The Julia guidelines?

Yes, but i think that for headers (Input, Output, or Fields) should be three ### because otherwise it displays as a huge title in the Jupyter Notebook. ATM we should have enough examples in this repo under docs/src and its subfolders.

I like that struct fields can be commented in the code.

ok, i haven't tried this feature!

from lazysets.jl.

update: i've finished the About section of the documentation, adding some words about "Contributing", and slightly reformulated the new paragraph from @viryfrederic .

from lazysets.jl.

Questions (meanwhile we discussed them all):

1. We have to update the results of Julia code evaluations, e.g., here.
   In this case I did not do it because we might want to check why we need more memory than before.
2. Do we want to have rules for line breaks in the signatures?
   Like "new line for every argument", "new line for return type"?
3. I find it more helpful to also see the return type in the docs.
   I would also add it to the actual function signature for additional type safety.
   Currently this is inconsistent (sometimes we have a return type, e.g., for σ, sometimes not, e.g., for dim).
4. We should merge the sections on developing in about.md and getting_started.md (I forgot that we already had this). Where should we put it?
5. Is it time to include doctests?
6. Do we want to have a template for documenting type parameters? → no
7. Sometimes we write function f() ... end and sometimes we write f() = ... for one-liners. → by convention we prefer the full function ... end
8. If we copy the signature, is it still reasonable to write optional arguments in brackets? → yes, to stay in line with official Julia docs
9. We have inconsistent exports, see, e.g., Ball2 vs. BallInf. → already resolved

from lazysets.jl.

Is it time to include doctests?

yes, this is a very good idea. i think we can put it in the milestone (to do after we get #14 merged)

from lazysets.jl.

1. We have to update the results of Julia code evaluations

OK, let me take care of updating that. also i can put it as a doctest. is there something for testing random outputs?

from lazysets.jl.

3. Do we want to have a template for documenting type parameters?

does the current info in the wiki qualify as such template?

Do we want to require such documentation?

yes, i think this should be required

from lazysets.jl.

4. I find it more helpful to also see the return type in the docs.

agreed. then let's add the output type for dim in all LazySets types.

from lazysets.jl.

Do we want to have a template for documenting type parameters?

does the current info in the wiki qualify as such template?

I do not think so. We see the type parameters in the first line, but there is no guide where to document the type parameters.

from lazysets.jl.

I find it more helpful to also see the return type in the docs.

agreed. then let's add the output type for dim in all LazySets types.

Good, then I will add them.
EDIT: We should use Int instead of Int64 everywhere, which is an alias for Int64 (Int32) on 64-(32-)bit machines.

EDIT: What do you think about the return type Void for "no return value"? Is this helpful?

from lazysets.jl.

EDIT: What do you think about the return type Void for "no return value"? Is this helpful?

seems good since

julia> typeof(nothing)
Void

in those cases where nothing is returned we can as well say it in the ### Output section

from lazysets.jl.

8. If we copy the signature, is it still reasonable to write optional arguments in brackets?

i've added 2 examples to the wiki, in this section, what do you think?

from lazysets.jl.

@mforets: Close?

from lazysets.jl.