My generated scaladoc is used within the company only, but we follow the naming convention, com.companyname.package1, com.companyname.package2
Is there a way to have scaladoc just list package1 and package2 instead of the fulled scoped namespaces? (Or, equivalently, to factor out the com.companyname prefix?)
I’m not sure I’m actually understanding the problem, since the full path doesn’t show in all that many places. What’s the pain point you’re trying to solve?
To make things concrete, here’s a reproducible example:
echo "foo" | sbt new scala/scala3.g8
cd foo
rm src/main/scala/Main.scala
(echo "package com.companyname.module1"; echo "trait Module1 { def fooer():Unit }") > src/main/scala/Module1.scala
(echo "package com.companyname.module2"; echo "trait Module2 { def fooer():Unit }") > src/main/scala/Module2.scala
(echo "package com.companyname.module2.sub"; echo "trait Module2b { def fooer():Unit }") > src/main/scala/Module2b.scala
sbt doc
For me, the above renders in firefox to:
I’d like to be able to have only “module1” and “module2” and “module2.sub” displayed on the left panel – removing the common com.companyname prefix. Maybe there is a way to turn on nesting? I am quite a novice as scaladoc.
This is mostly a minor cosmetic issue, but as it stands, I want to drop com.companyname from all my packages to make things look better.
Also, what does the top left drop-down “foo” do? Same question for the API button in the left panel?
Regards
Hmm. Okay, but I think that’s an artifact of the fact that you’re structuring your packages very strangely. Typically you would have a root src/main/scala/ folder, containing nested subfolders com/companyname/, and the modules go in there. It’s technically legal to put parallel nested names at the top level like this, but I don’t think I’ve ever seen it done in real code.
If you nest the code normally, you get properly nested listings – here’s a randomly-chosen example from the Scala 3 Scaladoc. The fact that your top levels are com.companyname is irrelevant: from Scala’s POV, they are just nested namespaces like any other, and your directory structure should usually match your package structure.
You’ve arguably found a bug here, since the nested-directory thing is technically just a convention. But unless you specifically need everything to be top level, I don’t recommend it – a fair amount of Scala tooling more or less assumes that convention.
Ahh. I don’t like deep directory structure because I try to maximize use of the command line – I rather not be punished with longer directories (more keystrokes) for introducing fine-grained namespaces. Scala making that optional is a real plus for me.
I’ll figure out the best way forward – thanks for your help.
I retried my minimal example following the nested directory structure convention.
mv foo fooOld
echo "foo" | sbt new scala/scala3.g8
cd foo
rm src/main/scala/Main.scala
rm -rf src/test # So there's no confusion
mkdir -p src/main/scala/com/companyname/module1
mkdir -p src/main/scala/com/companyname/module2/sub
(echo "package com.companyname.module1"; echo "trait Module1 { def fooer():Unit }") > src/main/scala/com/companyname/module1/Module1.scala
(echo "package com.companyname.module2"; echo "trait Module2 { def fooer():Unit }") > src/main/scala/com/companyname/module2/Module2.scala
(echo "package com.companyname.module2.sub"; echo "trait Module2b { def fooer():Unit }") > src/main/scala/com/companyname/module2/sub/Module2b.scala
sbt doc
This yields the following source files, with layout reflecting the package structure:
src/main/scala/com/companyname/module1/Module1.scala
src/main/scala/com/companyname/module2/sub/Module2b.scala
src/main/scala/com/companyname/module2/Module2.scala
I see that this source convention is recommended by the scalatra project.
Nonetheless, the result is the same as before.
I am using scala version 3.2.1; I get the same behavior from the command line scaladoc as sbt doc.
I must be missing something.
I couldn’t figure it out either. I read the docs for v2 and v3, scaladoc -help. Grepped source.
I had some hope for -skip-by-id:com.labor to collapse or ignore the top packages.
As usual, now I am frustrated and don’t want to use Scaladoc ever again. Either version.
Possibly, if a fix is needed, then -skip-by-id is a natural way to say, “I’m skipping these packages, don’t show the prefix in output either.” It does not currently mean skip subpackages:
I opened an issue on github:
I found something like what I mentioned about factorizing the package name prefix in this SO Q&A:
I’m aware that this system was inherited from Java, but in my view its an utterly appalling way to organise project files. Test files should be not be entangled with the Main files. Main is a dependency of Test. Main should not even need to know that Test exists. It should be possible to have your Test in another repository, or to swap out a Test component and replace it completely new Test without even touching the Main files.
I agree. (We should not conflate ancient conventions and any sense of necessity or “best practices”.)
I wanted to support this view, because (if I read it right) following the SO link from the ticket, someone says there something caustic.
Also, my previous comment was an expression of temporary frustration only. For some reason, documentation is both hard to write and hard to generate to its output format.
I hope the ticket gains traction. The other terrible convention is using com.acme for internal proprietary projects just to avoid conflicts in the universal namespace. Naming remains difficult. But tooling is also intended to make a difficult life a bit easier.
The jetbrains blog post (from the SO link) about this is decent:
Now I want it in vscode metals…