We have an API for OSX that we offer in 3 different languages;
Objective-C, C++, and Java.
For the C++ and The Objective C Languages we use Doxygen for all of the documentation. The same nice looking presentation that is applied to the class pages is also provided for the examples page (mainpage.h). I especially like the syntax coloring.
For the Java Language, we are using Maven. Since apple's dev environment doesn't really offer much for Java, we can use Maven for both documentation and its a decent build system as well. The class pages look as good as Doxygen in my opinion, but the presentation of the main examples page(examples.apt), looks pretty plain and uneventful.
Ive been searching for any reference on how to add some color to the page, but haven't really found anything.
My question:
Can anyone provide an example of how to implement coloring in the appropriate .apt file(examples.apt) or the sites.xml file?
There are two main locations for customizing the Javadocs. The first in in the pom.xml files. The second location is in the src/main/javadoc directory. You will probably have to create the src/main/javadoc directory yourself since it isn't normally in the initial set of directories.
See https://github.com/BradleyRoss/tutorials for how I set up some Javadoc settings. Look at the pom.xml in the parent module and the src/main/javadoc directory in tutorials-common module.
See https://maven.apache.org/plugins/maven-javadoc-plugin/examples/stylesheet-configuration.html for information on how to replace the stylesheet.css file with your own. That is probably where most of the color selection would go. It uses the stylesheetfile and stylesheet tags in the configuration section for the Javadoc plugin.
Maven apparently uses a modified version of the stylesheet.css file that comes with the JDK. You may want to compare the JDK and Maven versions to get some ideas on what you can change.
Related
I've been working on a Maven project consisting entirely of Java, and lately started to mix Scala code into it.
I'm amazed by the great expressiveness Scala offers, the easy use of scala-maven-plugin, and especially the incredible interoperability between Java and Scala.
However, I hit one inconvenience; according to the Maven's convention, Java's source code goes into src/main/java, whereas Scala's into src/main/scala. I found it quite cumbersome because I have to frequently go back and forth Java and Scala source files and every time I have to traverse the deep hierarchy of package directories (I often close tabs to keep my editor from cluttered).
So the question is: Is it recommended to maintain separate directories src/main/java and src/main/scala? If so, why?
To add more background, I've been working on the web application framework Wicket, whose convention is to put the HTML files alongside with their corresponding Java files. If we keep the directories separated, naturally the HTML files are separated as well (I don't think putting Scala files and corresponding HTML files in different directories makes sense). And then it goes "why I can't find Foo.html? Oh, I was looking for the wrong directory."
The source files themselves are very easy to distinguish both by humans and by machines by inspecting their extensions. I configured pom.xml to handle both Java and Scala put together in src/main/java and it worked (compiles and runs). On the other hand, separating directories poses a risk of defining conflicting classes in Java and in Scala, a careless mistake.
Well, I don't want to name a directory java if it contained not only Java's but also Scala's. But this is the only point I can come up with for separating directories.
(Edit: I've come up with a workaround-interpretation; let us think java stands for Java Virtual Machine. In this way, having src/main/c doesn't contradict if we ever decided to use JNI because C doesn't run on JVM.)
Oh, and one more point; my project is not intended as an open-source project; development convenience is preferred than trying hard to follow conventions.
This question is inspired by this answer.
I'd say yes, re-use code as much as possible. Maybe in future you can use this Java piece somewhere else...
As you probably know, you can use Java in Scala projects but not Scala in Java projects. So in this specific example it will help you with (future?) Java projects. If you want to re-use a piece of your Java code you can do that in either Java projects as well as Scala projects.
So i.m.h.o. it doesn't stop at the src/main/... but you should really put them even in different components.
Btw, little side note: if I'm correct, Wicket allows you to put the html somewhere else too, even in a different project... I saw it being handy (only) once, where we had to create different frontend for different clients of us. The java code stayed the same, the wicket-id's as well, but the html changed everywhere. Though it did give us some problems as well using the Qwicky plugin, as it could not find the html files in our IDE anymore.
I'm writing documentation for my java file. In that documentation, I want to add some html links at the end of each generated file. For that, what I have to use while writing java documentation?
If you are using Eclipse as IDE, you can use the plugin JAutodoc:
http://jautodoc.sourceforge.net/
To add a default text at the beggining of each text file.
According to the javadoc manual (can't find a newer version right now), you should use -footer when you generate your java API documentation from the CLI, for instance:
javadoc -footer "<b>Copyright 2015 Lakshmi Prasanna</b><br>" com.mypackage
Here's a similar example, but that uses -header instead.
Now, if you use a good IDE, at the very least it should allow you to type that somewhere in the project settings. Back in the day Eclipse wasn't very flexible, so I had to make an Ant script (yuck).
EDIT:
One limitation with this approach is that the CLI -options depend on the tool. This works with the standard javadoc command but might not work with another vendor's doclet. However I'm not sure there's a universal way to achieve what the OP asked.
Anyway, it seems to be: NOT -footer but -bottom.
I'm wondering if there is a website with like a list of java libraries/jars where you can browse around and see if theres something you could use. like when you make your own program which then contains lots of useful stuff.
Sort of like a website where people share their code, for public use.
SourceForge
Freecode (Freshmeat)
Google Code
github
Java.net
http://mvnrepository.com - if you know jar name or package name. it will provide you available versions and pom/ivy/gradle coordinates for copy/paste.
http://findjar.com/ - helps you to find jar containing this f*%^ing class nobody knows about (and then you can search mvnrepository to look if it is available for maven build - if not, the best is just ignore this library as this is probably of low quality or not yet released to public properly)
I need to document a Java project. I am a C# Programmer and Systems Analyst. But I am new to Java.
I have the directories checked out of SVN.
These directories include the source directories, WEB-INF and other files required for definition of the project, classpath etc.
I understand that the files essentially belong either of the following three categories
Source code files / directories that are based on the way the packages are structured (.Java)
Directories / Files required for project definition, compiler settings etc
Files required for deployment.
The project is (as most Java projects are) an Eclipse based project designed to be hosted on Tomcat.
Now, give the above information I have decided to document the entire project into three different documents
A document explaining the source code etc.
A document explaining the purpose of the files & directories that are required for compiler settings, project definitions etc
A document that explains the deployment directory structure.
Or alternatively I could create a single document with three sections that explain 1-3 above.
Now, questions
Is this the right approach?
Are there any other methodologies that I can follow or borrow from?
Are there any other suggestions etc that you can add to this approach
Any additional info will be of use.
Thanks a ton in advance
I think you're on the right track. In a project you need to address three documentation needs
User Documentation
This include a document stating what the application is about, and how to start it/access ut.
Development Documentation
This includes at least the Javadocs, a description of the source code directory structure, the build process (ie, how to compile the project), compiler time dependencies, development standards, how to set up a database for development, and how to get the source code from the repository. These are the minimum you need to get others to work in your project. Additionally as the project complexity grows I like to put together a series of "How To" for common tasks in the system (ie: "How to leave an Audit Trail for a given Operation", "How to use the Logging framework", "How to manage exceptions", etc), a description of the main Domain classes and their relationship. If you use a database, and the database schema is not exactly one-on-one with the domain classes, I'll add a schema documentation.
Deployment Documentation
This is basically the installation manual of the application, describing any steps needed to make it run: putting the WAR in Tomcat, running scripts against a database, configuration files that needs to be modified, etc,etc.
As you see, you already partially addressed two of them. Start small and simple, and add the rest as the need arises.
It also helps to check if your organization has any documentation standard.
Try Javadocs link. Written with proper planning, it will address all your points above.
A document explaining the source code etc.
Yes. Approach this as if your reader was someone trying to get familiar with the reasons why the project was written (why was this project created), as well as the overall architecture of the project.
The Javadocs on the source classes should explain what each class does. Your document should tie the Javadocs together, like a tutorial.
A document explaining the purpose of the files & directories that are required for compiler settings, project definitions etc.
Yes.
A document that explains the deployment directory structure.
I suppose that's what your build scripts do. Perhaps I don't understand what you expect this document to accomplish.
Are there any other suggestions etc that you can add to this approach
Unless this is the first time anyone in your development group has documented a Java project, there should be other documentation. See what they've done.
If you are the first, then I'd say this was a good start. I'd be most interested in the first document. Your new programmers would like the second document.
I wanted to use JET (Java Emitter Templates)
in my Netbeans projects, but had to find out that JET
heavily depends on Eclipse libraries.
Is there something similar to JET, but as a standalone project?
Something which is open source and well maintained?
Futhermore, is "code generation" the common term for such tools?
If you are using Maven, you can use JET templates with the maven-jet-plugin.
This seems to be the source code. And here the documentation.
It is not actively maintained but works pretty well and follows the JET spec.
I've used it with templates and skeletons.
It's self contained, doesn't depend on Eclipse, and doesn't introduce any transitive dependencies to your project.
Indeed JET is very tied with Eclipse.
If you want to generate code without Eclipse you should use another solution.
You can choose another template engine like Velocity (https://velocity.apache.org/) or FreeMarker (https://freemarker.apache.org/).
Or you can choose a code generator working by itself independently of any IDE.
For example "Telosys Command Line Interface" : http://www.telosys.org/
From what I know, JET is something like JSP, no?
Java Emitter Templates are very similar to Java Server Pages (JSPs). Both JETs and JSPs use the same syntax, and are compiled to Java behind the scenes. Both are used to separate the responsibility for rendering pages from the model and controller. Both accept objects passed into them as an input argument, both allow inserting string values within code ("expressions"), and allow direct use of Java code to perform loops, declare variable, or perform logical flows ("scriptlets"). Both are good ways of representing the structure of a generated object (web page, Java class, or file) while supporting customization of the details.
JETs differ from JSPs in a few key ways. In a JET, the structure of the markup may be changed to support generating code in different languages. Typically the input to a JET will be a configuration file and not user input (though there is nothing forbidding this). And also typically, JET processing will take place only once for a given workflow. These are not technical limitations, and you may find uses for JETs which are quite different...
ibm.com
Here are a few links to get you started on JSP, if that sounds like what you need:
sun.com
netbeans.org
Look for "template engine" for these types of tools.
A couple you might want to look at:
Apache Velocity (http://velocity.apache.org/)
StringTemplate (http://stringtemplate.org/)
I ended up using ERB (Ruby's template engine).
Works great in Netbeans!
I define custom ant task which generates source files by calling ERB (whose results are placed inside a non-versioned special directory).
The ant task is overriding Netbeans' "-pre-compile" task.