https://kotlinlang.org logo
Join Slack
Powered by
Please let me know which KDoc you prefer or if you...
# codingconventions
e
Please let me know which KDoc you prefer or if you have better suggestions. It would be easier to write if the width and height parameters were named 
width
(instead of 
w
) and 
height
(instead of 
h
), but those are instance variables in the superclass (
JPanel
). I'm a professor creating a problem set, so there aren't team guidelines I can follow. I just want to set a good example. 1️⃣
Copy code
/**
     * Draws a rectangle with the specified [x] and [y] coordinates,
     * [outlineColor], and [fillColor]. The parameters [w] and [h]
     * specify the width and height.
     */
2️⃣
Copy code
/**
 * Draws a rectangle with width [w] and height [h] with the specified 
 * [x] and [y] coordinates,[outlineColor], and [fillColor].
 */
1️⃣ 1
e
Copy code
/** Draws a rectangle with [width][w] and [height][h]
🙏 1
e
@ephemient I did as you suggested, but the generated html does not show the connection between 
width
and 
w
. The link just goes to the function and does not reference 
w
.
Copy code
<p class="paragraph">Draws a rectangle with <a href="draw-rectangle.html">width</a> and <a href="draw-rectangle.html">height</a> with the specified <a href="draw-rectangle.html">x</a> and <a href="draw-rectangle.html">y</a> coordinates, <a href="draw-rectangle.html">outlineColor</a>, and <a href="draw-rectangle.html">fillColor</a>.</p>
e
does it need to be 
[getX]
perhaps?
e
I'm not sure why it would be 
[getX]
when I was asking about 
width
and 
w
. I was able to refactor the code and rename the parameters 
width
and 
height
, so my question is largely moot (although it would be great if KDoc were better specified). Thanks for your help.
e
I meant it as shorthand for 
[width][getW]
[height][getH]
. assuming it's coming from Java, since I wasn't sure why else 
[width][w]
wouldn't have worked for you… it does for me, at least in the IDE rendered KDoc (I don't have a modern Dokka test project set up)
c
Dokka doesn't have a separate page for arguments (AFAIR), so the link you generate leads to the current page 😕
I have an idea how to improve this but I can't explore it at the moment
e
So there's one (and only one) thing I like better about Java than Kotlin. 🙂
c
What is it?
e
javadoc
c
Really???
I hate javadoc ahah
<p>
e
I don't mind writing it and find it very useful.
I agree with you about not liking the HTML.
c
(@link foo}
What do you think javadoc does better than kdoc?
e
Makes clear what all the parameters mean and provides a way for stating constraints.
c
Do you have an example?
e
Just about anything in the Java standard library documentation, but it's not necessary for us to agree. À chacun son goût.
e
KDoc can represent parameters, Dokka just doesn't render them separately
👍 1
e
You're right. My gripe is with Dokka, not KDoc.
2 Views
Open in Slack
PreviousNext
Powered by