Hi, I would like to import Javadoc into my Flare project. I realize I can't do this directly. Do you have any suggestions about what intermediate step/format to use, such as HTML, Word, PDF?
Thanks for any suggestions,
Jennifer
import Javadoc into Flare
Re: import Javadoc into Flare
I would generate the HTML out of the Javadoc and start there. Since Javadoc files are a combination of code and text, you're better off letting it generate the static content then importing the HTML. Did things change? You mentioned Word and PDF, the last time I looked at Javadoc, only HTML was supported.
-
clturner222
- Jr. Propeller Head
- Posts: 2
- Joined: Mon Apr 22, 2013 10:03 am
Re: import Javadoc into Flare
Ahhh, please do not be discouraged by this post!
Do you mind if I ask why you need to import Javadocs into Flare? It can be done, it has been done (there was a session about API docs and Flare at 2013's MadWorld), but it isn't an enviable task.
Generally, when I've been asked to work with API documentation it's hit from a few directions.
1-Someone just wants a pass at them for completeness and to make sure they're correct. A quick edit pass is usually asked for as well
--Importing them into Flare just to do ^this is a REAL pain and much easier to do natively
2-Someone who doesn't really understand the nature of API documentation wants them to look very fancy and pretty (like the consumer facing documentation!)
--I usually laugh, walk away, laugh some more and decide if this is a battle I (or someone higher up the food chain) can win. API documentation is NOT consumer facing documentation. Generally, the developers looking at it tend to get kind of agitated when it's treated as such; they want to get it, get their info and get out. If the docs are well organized and complete and look like they expect them to look, they're pretty happy.
---That said? You can do a lot with the CSS to make it prettier and easier to use, but you wouldn't use Flare for that.
3-The developers are lazy and don't want to comment their code, so it's up to the Tech Writers to do it for them (sorry, but that's the truth in some cases)
--See the first response to #2
---If you're that ever so rare unicorn of Tech Doc that bleeds code? Well, ask for a raise and go for it! But, again, probably want to go native and not tackle it in Flare.
4-All of the above
--Wow, okay. People need to start talking to each other and get on the same page!
5-Something completely different
--Define, define, define
If you have to get them into Flare, you will probably need something external to render the output and give it to a Flare project as the Javadocs are updated (which can be quite frequently, depending on how often the code is being touched). Working with a Build system, repositories, etc. and having people point you in the proper directions to get and keep the living content up-to-date is essential and usually requires a bit of collaboration with a developer or two and a BuildMaster. Often you end up with an Internal API doc and an External version. The internal is what your developers use and the external is separate, somewhat independent and what gets published for the outside world to see.
As I said, unless someone has a really good reason (private vs. public APIs) and understands the work involved, Flare may not be the best option.
-C
Do you mind if I ask why you need to import Javadocs into Flare? It can be done, it has been done (there was a session about API docs and Flare at 2013's MadWorld), but it isn't an enviable task.
Generally, when I've been asked to work with API documentation it's hit from a few directions.
1-Someone just wants a pass at them for completeness and to make sure they're correct. A quick edit pass is usually asked for as well
--Importing them into Flare just to do ^this is a REAL pain and much easier to do natively
2-Someone who doesn't really understand the nature of API documentation wants them to look very fancy and pretty (like the consumer facing documentation!)
--I usually laugh, walk away, laugh some more and decide if this is a battle I (or someone higher up the food chain) can win. API documentation is NOT consumer facing documentation. Generally, the developers looking at it tend to get kind of agitated when it's treated as such; they want to get it, get their info and get out. If the docs are well organized and complete and look like they expect them to look, they're pretty happy.
---That said? You can do a lot with the CSS to make it prettier and easier to use, but you wouldn't use Flare for that.
3-The developers are lazy and don't want to comment their code, so it's up to the Tech Writers to do it for them (sorry, but that's the truth in some cases)
--See the first response to #2
---If you're that ever so rare unicorn of Tech Doc that bleeds code? Well, ask for a raise and go for it! But, again, probably want to go native and not tackle it in Flare.
4-All of the above
--Wow, okay. People need to start talking to each other and get on the same page!
5-Something completely different
--Define, define, define
If you have to get them into Flare, you will probably need something external to render the output and give it to a Flare project as the Javadocs are updated (which can be quite frequently, depending on how often the code is being touched). Working with a Build system, repositories, etc. and having people point you in the proper directions to get and keep the living content up-to-date is essential and usually requires a bit of collaboration with a developer or two and a BuildMaster. Often you end up with an Internal API doc and an External version. The internal is what your developers use and the external is separate, somewhat independent and what gets published for the outside world to see.
As I said, unless someone has a really good reason (private vs. public APIs) and understands the work involved, Flare may not be the best option.
-C