E.g.

• markdown support
• html support (as currently doing)
• asciidoctor

so developers could use their wanted markup...

As an feature when no slash is given on a resource the same path as of element is automatically used

de.jcup.testpath.UseCase1.java with example resource "test.html" searches automatically inside

de/jcup/testpath/teset.html

It works for HTML but not for PNG

alphabetical ordering in a tech info table (by its type) would be more readable - and type parts could be groupd also.

What about concepts knowing use cases? And what about linking from text to use cases?

Currently only use cases know the concepts (reason was that a use case can simple removed and this has no effect to architecture it self)

When internal links are possible (see #6)
we should create a validator for internal links too - otherwise only at rendering time a wrong code2doc://-link will trigger errors on rendering engines (like docbook4j - fo etc.)

In use cases the setup is able to do:

setup.addRole(Role r)
setup.addRole(Role r, Constraint c);

• because Roles are elements so all must be wellknown following must be possible:
  On generation time it is clear which roles are NOT allowed for the use case. These rols shall be marked in documented as not able to do the operation!

Currently locale=null means default language (like in resource bundles).

while defining content in a setup this okay. But inside generation getContent() should use not null but setDefaultLocale instead (and this could be used by generator)
so we could remove getContent(Locale) completely!

Advantage: no more changes necessary for freemarker templates - thiese must only use content...

e.g Section 2.1, “Create a concept” [6] used instead "create a concept"...

Also it would be possible to write extensions for this.

Idea would be like:

code2doc-extension-utils
=> EntityModelPictureCreator.createClassDiagramPictureFor(YourProject.class);

see also #20

In some projects the original concepts are done in tracking systems like JIRA.

Maybe it would be nice to have a semantic part like
setup.addLinkToIssue(#18) ?

We have done this before for wiki entries
(setup.setWikiURL(..) )

Ordering output of elements in rendered document must be alphabetical ascending

e.g.
UC_1.class
UC_2.class
UC_3.class

must always have this ordering.
UC_1, UC_2, UC_3 !

e.g.

setup.addRole(role1,constraint1);
setup.addRole(role2)

--> should result in output:

role1 constraint1
rolw2 (no constraints)

Following roles are not allowed for this use case: role3, role4, role5, role6.

But this feature should be configurable (param.set("code2doc.usecase.show-unsupported-roles","true")

Currently e.g. Specification impl is being very ugly implented - needs to be refactored.

Every impl should have a dedicated hashcode equals (and maybe a to string impl)

Usecases contains a table (when defined) of possible roles.

The output must be ordered alphabetical

Remove brackets at copyright note at end of license file..

currently a use case can only be setup with

setup.addRole(role)
setup.addRole(role, constraint)

it must be also possible to do
setup.addRole(role, constraint1, constraint2, ..)

API and templates must provide this

currently when you got an image and you want it inside your described text you must divide
text into different files and add it into use case def...

e.g.
content().addTextResource("resource1.html").addPictureResource("picture1.png").addTextResource("resource2.html").

very ugly to use...

Write a extension to do auto scnapshots for use cases where example url is set!

/**
 *  @return path or <code>null</code> if no snapshot can be created for given object
 *
 */
public String createExampleURLSnapshot(Object  object)

This should be an abstract implementation so only dedicated file names etc. are possible. The handling itself (e.g. using Selenium-Test-APi to get snapshots must be done in projects itself!)

A snapshot file renderer should do the internal parts like add to to model etc.

When adding example picture the output in PDF does not work 100%. Bigger pictures are not shown completeley.

Should be Like in UseCase:

protected void doSetup(UseCaseSetup setup){
        setup.setExamplePictureResource(...)
}

=>

protected void doSetup(ArchitectureSetup setup){
        setup.setBigPictureResource(...)
}

Purpose is to have a dedicated position in document for such kind of pictures.
(A big picture should always give you straight forward view of the architecture)

see also:
#20
#21

Currently inside a document following ordering happens:
UC_USERS_2_USERS_OVERVIEW
UC_USERS_1_USERS_SHOWLIST

But it must be

UC_USERS_1_USERS_SHOWLIST
UC_USERS_2_USERS_OVERVIEW

• means : simple sorting by class name...

This is similar to #31 - but the allowed file format will be only html. It should prepare for other markups too.

Something like a Registry for file supports should be available

TextResourceRegistry.register(".html",  new DocbookHTMLMarkupSupport());

So e.g. addTextResource("name.html") is allowed but not ("name.txt").

code2doc-core:
=>BigPictureResourceExtension
... iplementation could use EntityModelPictureCreator(#21) (or any other API...) a dedicated library

Needs at least implementation of #19

Currently when an error happens we got a error log entry, an outpt error marker entry instead of correct one... and also and xml comment about the error.

the comments are using -- which is not allowed inside xml comments itself

on the other side it makes no senso to add comments when its also inside the ouptut.

So remove the comments.

For markup HTML

Currently a missing description does result in

• showing headline (always)
• showing a standard text for not defined description

but content elements have always a content where the content can be described more precise.
So when no description is set it does not matter

=> when no description is set

• no headline of description
• no standard text for missing description

Discussion about missing features in code2doc

This is a discussion issue about missing features in code2doc. In lack of a forum all issues labeled with "discussion" are used to handle this kind of messaging.

👍

Via Code2DocExtension projects should be able to support additional information.

E.g. "ExampleURLExtension" -> builds example urls automatically by project information.

Currently <<ahref='...'>linktext supports only normal hyperlinks.

It would be very convenient to have something like

<a href='code2doc://package1.subpackage2.ConceptClass.class'>linktext
<a href='code2doc://package1.subpackage2.UseCaseClass.class'>linktext
<a href='code2doc://package1.subpackage2.ArchitectureClass.class'>linktext
<a href='code2doc://package1.subpackage2.RoleClass.class'>linktext
<a href='code2doc://package1.subpackage2.ConstraintClass.class'>linktext

The freemarker templates currently doing many unnecessary empty lines on output.

One of top reasons (or maybe the only one) is that macro calls are always handled as a line - even when no output is done at all (e.g. on debug logging).

This should be improved - so output of xml is more pretty.

Currently Specificaiton is representing a write only interface, so no unnecessary getters are available (does not confuse...)

But for custom generators there must be something like
ReadableSpecification

or maybe simple : SpecificationModel ?

Anyway.. the interface should only support read methods (as currently used by the FTL types directly to specification impl). Normaly only these calls must be transfered to interfaces.

This is a little bit familiar with #35

Wiki links should be shown on top of element in generated documentation .

Currently its too difficult/verbose to describe documentation via code.

It should be much simpler. Also the describing of text should be done nearly only via markdown or asciidoctor (TBD).

Tech info table in output pdf is not sorted by title name

e.g.
Technical information - my use case
Technical information - my use case (group1)
Technical information - my use case (group2)

What about a wiki content grabber? or any other project content grabber?

Some projects could define their content already in a wiki - its very easy to use, smooth and normally has wyswig editors etc.

So the idea would be to make an Code2DocExtension available for projects where they could provide
wiki content.

Would this be nice?

ERROR main - resource not found for resource path:myTasks.png

does result only errors in log but no explicit runtime exception.
Instead only freemarker template does result in error:

FreeMarker template error:
The following has evaluated to null or missing:
==> transformer.transformToFile(useCase.examplePictureResourcePath) [in template "macro/usecase.ftl" at line 55, column 45]

Currently the collection of annotated enums results in simple addLinkToURL in tech info but not in addLinkToJava(id, enum)

So the transformer is not able to handle enums correctly in output when transformToString is called in templates