<derkork>
Hey there, I was wondering if there is some agreed-upon way of documenting modules and functions in a way that tools can read the documentation (e.g. say what a module does and what the parameters do)? Something like documentation comments in other programming languages.
ur5us has joined #openscad
rvt_ has joined #openscad
<J2252>
derkork never seen that
J2252 is now known as J22
<derkork>
so if i would write a library for others to use, there is no standardized way to make the documentation.
<J22>
so many libraries have no documentation at all
<teepee>
I'd like to have something like the """ <text> """ with markup
<derkork>
i noticed, i checked a few. some use doxygen, some have their complete own formats, some have no documentation at all
<teepee>
similar to what python uses, but as there's no code yet, I'm open for other options :)
<teepee>
the benefit of that integrated solution would be that we could use it in GUI too
<derkork>
well not sure if it would be necessary to change the _language_ specification for that, i guess just having a standardized way to put the comments would help... e.g. using existing comments
<derkork>
```swift
<derkork>
well not sure if it would be necessary to change the _language_ specification for that, i guess just having a standardized way to put the comments would help... e.g. using existing comments like this:
<derkork>
* This does foo the boodibogofier.
<derkork>
* @param a [number] - bogofying rounds to run.
<derkork>
* @param b [vector3] - direction to foo into.
<derkork>
* @param c [bool] - whether to foo in the center.
<derkork>
*/
<derkork>
module foo(a,b,c) {
<derkork>
}
<derkork>
is there a code block?
<teepee>
nope, best to use some paste service for multi line stuff
<teepee>
there's no way to standardize by asking people :)
<teepee>
but then you can use whatever you want in that case
rvt_ has quit [Quit: rvt_]
<teepee>
well, I guess we *could* parse even more comments, but I really don't like that
<derkork>
well i am not pushing for a standard here. i just wanted to use an agreed upon convention if there is one.
<derkork>
but seems there is none, so i guess i am free to use whatever i deem right.
<teepee>
there's nobody who could push for some standard across libraries
<teepee>
that would be the benefit of an integrated solution as it provides some addititional features giving some incentive to use that one
aiyion has quit [Remote host closed the connection]
aiyion has joined #openscad
<teepee>
now I don't know the future, but I'm pretty sure if I'll post on the mailing list asking all library writers to go with a specific documentation version, I'll be ignored ;-)
<teepee>
which is fine :)
<derkork>
oh yes for sure.
<teepee>
the library page has a list of libs that have good to awesome documentation, I've not really checked what everyone is using
<derkork>
okay, so now i know, I'll put this on the shelf for now.
<derkork>
it's all over the place, i checked a few of these.
<teepee>
I'd say, start with what you like
<teepee>
the most important part is the documentation content
<derkork>
yep.
<teepee>
everything else is more a specific formatting which is annoying to change, but not a big deal compared to having docs vs. not having any
<derkork>
makes sense. thank you!
<teepee>
and having docs is one of the 2 entry points to the official library list if you are writing a library :D
ur5us has quit [Ping timeout: 240 seconds]
<J22>
still we could offer a suggestion in wiki for it or?
<J22>
like "best practice" use doxygen if you don't have your own style
<teepee>
sure, some sort of guideline would be useful
<teepee>
library-writers-guide :)
little_blossom_ has joined #openscad
little_blossom has quit [Ping timeout: 256 seconds]
nedko has quit [Remote host closed the connection]
<InPhase>
There are a couple of acceptable ways to do that. This is one: https://bpa.st/UU2A
<InPhase>
Almost what you did, but you should have the indenting present for all parameters within a function.
<InPhase>
Optionally you can also have the trailing parentheses line up for the close of each opening: https://bpa.st/AKAA There are times when this prevents confusion, it's just a little less vertically compact.
<J22>
I see .. makes sense , ill try to get used to that
<J22>
i think ill use the first one
<J22>
( i mean i am doing this for others - i am happy with one line Ü )
<InPhase>
I am not always consistent myself between those styles, but tend to adapt based on the complexity of the thing in question. If it's more complicatedly nested, or something going to be shared and reused widely, being more disciplined about the closing brackets is more explicit and clear and reduces chances for mental parsing confusion.
<J22>
hmm parenthesis () didn't invoke folding
<J22>
yeah i just switched to the later version as it is consistent with my [] and {} style
rvt_ has joined #openscad
<J22>
but seems the lexer is not designed to deal with multi lined parenthesis
<J22>
an official "bend" module (so it is working on objects not just points) would be quite useful to create a lot of nice objects - and it is pretty simple.
<joseph_>
This might not be suitable for a feature request, but I wanted to mention a common mistake I accidentally cause as a user: putting a semicolon after `translate([x,y,z]);` This means my intended translation will not occur.
<joseph_>
Obviously putting a semicolon right after the translate function is wrong, but I always miss it at first because there is no warning displayed during parsing. Would it be possible to add such a warning without breakage? Has this been brought up before?
castawayc has quit [Ping timeout: 276 seconds]
castaway has quit [Ping timeout: 246 seconds]
castaway has joined #openscad
castawayc has joined #openscad
<teepee>
joseph_: yes, I think that should give a warning
<teepee>
there's lots of discussion about warnings and quite a number have been added over the last couple of years
<teepee>
not sure about this specifically, but there's some for the opposite case: cube() cube();
<InPhase>
Yeah, I think that should probably be a warning.
qeed has quit [Quit: qeed]
<InPhase>
That then leads to the question, should this be a warning? module MyTranslate(x) { translate(x) children(); } MyTranslate([10, 0, 0]); { sphere(5); cube(4); }
<InPhase>
We treat the children() as an empty geometry there. Should children() be a warning if there are no children?
<InPhase>
This is trickier because there are probably people who got used to empty children() being ignored in existing code.